Designing for Model Deprecations with Virtual Models and Staged Cutovers

On July 23, 2026, OpenAI is scheduled to shut down 15 listed model entries — a mix of dated snapshots and aliases spanning Codex, chat, deep-research, search, audio, realtime, and computer-use APIs, per its deprecations page. The immediate task is migration. The durable engineering problem is dependency ownership: application code should not depend directly on identifiers whose lifetimes are controlled by a model provider.

This post describes a safer operating pattern — inventory current usage, place a stable virtual-model alias between applications and provider models, evaluate replacements against workload-specific tests, shift synchronous traffic through a weighted canary, and preserve a fast rollback path.

1. Read the Calendar Like an SRE

OpenAI's deprecations page defines the semantics directly: a model becomes deprecated at the moment of announcement — it still works, but it now has a shutdown date — and once shut down, requests to it no longer resolve. The published notice policy is at least six months for generally available models and at least three months for specialized variants such as Codex and chat-latest models. Preview models may receive notice as short as two weeks, and OpenAI explicitly advises against using previews for business-critical production workloads unless the team can migrate quickly (OpenAI deprecations page).

The April 22 announcement established two concentrated shutdown batches: 15 listed entries on July 23, and on October 23 a further set of legacy GPT-3.5, GPT-4, GPT-4 Turbo, GPT-4.1 Nano, GPT-4o, and o-series snapshots and aliases, along with gpt-image-1 and several fine-tuned base-model families. Note what October 23 is not: it is not the entire GPT-4 family, and it is not the entire o-series — the dated o3-2025-04-16 and o3-pro-2025-06-10 snapshots are listed separately for December 11, and only the gpt-4o-2024-05-13 snapshot appears from the GPT-4o line.

The image-model sequence deserves attention as precedent. When DALL·E 2 and 3 shut down on May 12, OpenAI had listed gpt-image-2, gpt-image-1, or gpt-image-1-mini as recommended replacements. Teams that selected gpt-image-1-mini must now migrate again before its December 1 shutdown, and gpt-image-1 itself is scheduled for October 23. The lesson generalizes: the migration target can also be on the calendar, and an architecture whose response to deprecation is editing model strings everywhere and redeploying will repeat that work on the vendor's cadence.

Nor is this one provider's pattern. Anthropic lists Claude Opus 4.1 for retirement on August 5, 2026, with a documented policy of at least 60 days' notice for publicly released models (Anthropic model deprecations). Google lists October 16, 2026 as the earliest shutdown for Gemini 2.5 Pro, Flash, and Flash-Lite, and one preview model — gemini-3.1-flash-lite-preview — ran from March 3 to May 25, 2026, under three months from release to shutdown (Gemini deprecations). DeepSeek's own API documentation says the legacy aliases deepseek-chat and deepseek-reasoner will be deprecated on July 24, 2026, mapping them for compatibility to the non-thinking and thinking modes of deepseek-v4-flash; it does not identify that date as a shutdown (DeepSeek models and pricing). These four providers all publish active model-lifecycle changes; their notice periods and migration mappings differ.

2. The Inventory Problem: You Cannot Migrate What You Cannot Find

Every migration guide starts with "audit your usage," and every platform team knows why that step slips: model IDs hide in service configs, notebook constants, CI pipelines, framework defaults, coding-agent configuration files, and third-party tools nobody remembers adopting. Grep finds the strings in your repositories; it does not find the volume, the owner, or the traffic that originates outside version control. The reliable census is observational: if every model call crosses one gateway, then per-model usage — split by team, application, user, and virtual account, with cost attached — is a dashboard query, and "who still calls this retiring model" has a live answer with names and dollar figures on it. Anthropic's own guidance points the same direction, recommending customers export per-key, per-model usage audits before migrating. That census is also the prioritization function: a model with three residual calls a day from a forgotten batch job is a ticket; one carrying a customer-facing feature at six figures a month is a project.

‍

‍