DeepSeek V4 Legacy Model Names: An OpenAI-Compatible Migration Runbook

Why This Topic Matters Now

The Sep 21 keyword report again highlighted DeepSeek API, DeepSeek V4, and DeepSeek pricing intent, but the most useful new cut is compatibility drift. DeepSeek's current official page distinguishes the `deepseek-flash` model name from legacy names such as `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp`. It says the legacy names remain accepted while the retired requests are served by DeepSeek-V4.1-Flash. For an OpenAI-compatible client, that is a migration signal: a request can succeed while the configuration is already stale.

This runbook is for Tier 1 and Tier 2 teams that need to preserve client stability while model identifiers evolve. It separates provider alias behavior from AIWave gateway route evidence, then adds concurrency, usage, and rollback checks. The goal is not to promise that an alias will remain forever. The goal is to make the alias transition observable, reversible, and safe for a team that has to explain which model contract was tested.

Source Facts Checked Today

AIWave /api/pricing was checked from production on Sep 22, 2026 and returned HTTP 200, success=true, 74 live route rows, pricing_version a42d372ccf0b5dd13ecf71203521f9d2, auto_groups=['default'], group_ratio default=1 and vip=0.9, and OpenAI-compatible endpoint types for the selected routes. The public /api/v1/pricing endpoint returned HTTP 200 with 56 dated USD rows, pricing_version 83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5, checked=2026-09-10, and updated_at=2026-09-18. Keep live route availability separate from the dated public USD snapshot.

DeepSeek's official pricing page checked on Sep 22, 2026 lists `deepseek-flash` and `deepseek-v4-pro`, shows a 1M context length, a maximum output of 384K, and says the legacy names `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` are still accepted even though the corresponding models are retired. It lists concurrency limits of 2500 for Flash and 500 for Pro, plus separate cache-hit, cache-miss, output, peak, and off-peak rows.

The dated AIWave public rows checked in this run list `deepseek-v4-flash` at $0.638 input, $0.0202884 cache-hit input, and $1.914 output per 1M tokens, and `deepseek-v4-pro` at $1.914 input, $0.0637362 cache-hit input, and $5.742 output per 1M tokens. Both rows carry effective_date 2026-08-27. These are gateway base-rate records and should not be merged with DeepSeek's direct peak-window table.

Planning Matrix

A source-dated planning matrix keeps the page useful for engineers and procurement reviewers. It turns a search query into an auditable route decision instead of a loose model preference.

Implementation Pattern

The implementation pattern keeps credentials as placeholders, pins the AIWave base URL, records the model, and leaves room for route-specific controls. Production applications should move credentials into environment or secret storage.

from dataclasses import dataclass
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY_HERE", base_url="https://aiwave.live/v1")

@dataclass
class ModelCandidate:
    requested: str
    fallback: str
    checked_at: str

policy = ModelCandidate(
    requested="deepseek-flash",
    fallback="deepseek-v4-flash",
    checked_at="2026-09-22",
)

response = client.chat.completions.create(
    model=policy.requested,
    messages=[{"role": "user", "content": "Return one migration check."}],
    temperature=0.0,
    max_tokens=120,
)
print({"finish": response.choices[0].finish_reason,
       "usage": response.usage})

Make the Search Intent Operational

For a DeepSeek model-name compatibility runbook, the useful artifact is a small operating policy: approved model IDs, source date, request shape, data class, output ceiling, tool allowance, retry ceiling, and owner. Put those fields in the release record before a trial begins so engineering, finance, and procurement review the same decision rather than three different interpretations of a model name.

Separate Live Routes From Dated Rates

AIWave's live pricing response answers which route rows and endpoint types are available now. The public pricing JSON answers which dated USD base-rate rows were published for forecasting. They are related evidence, not interchangeable tables. Store both URLs, versions, checked dates, model IDs, and the account-group context used by the forecast.

Build a Small Acceptance Set

A production canary should include a normal request, repeated context, a long input, a malformed request, and a stop-condition case. Capture request ID, model ID, status, input tokens, cached input when exposed, output tokens, tool calls, retries, finish reason, and reviewer outcome. This turns a blog recommendation into evidence that can survive a route or provider update.

Keep the Request Boundary Explicit

OpenAI compatibility reduces client changes; it does not decide what data may cross a route. Keep credentials server side, use an obvious placeholder in examples, redact test fixtures, and attach a data-class decision to the route policy. A model alias, feature flag, or billing mode should never silently widen the approved data boundary.

Use Bounded Recovery

Retry only errors that are safe to retry, and give every fallback an attempt ceiling. Preserve the original request ID and record the stop reason. For tool-using agents, distinguish a provider error, a validation failure, a policy rejection, and a budget stop. Silent loops make both reliability and cost impossible to explain.

Use AIWave's Evidence Layer

Use the Models docs, Chat Completions docs, dated Pricing JSON, and Status. Recheck the live route table before rollout, the dated pricing JSON before a budget review, the status page before a launch window, and the trust page before procurement. Keep the checked dates visible in the internal decision record instead of presenting a volatile provider page as a permanent quote.

Release Gate

Promotion is ready when the official provider source is dated, the AIWave route is rechecked, the representative canary passes, the billing fields are understood, and a named owner can stop or reverse the change. If any of those fields are unknown, label the work as a trial rather than production.