Sora API Migration Guide: Review the Contract Before Switching

Begin with the official retirement notice

OpenAI’s API deprecations page lists September 24, 2026 as the removal date for the Videos API and the Sora 2 model aliases and snapshots named in that notice. The notice does not name a replacement for those entries. Check the official documentation before relying on a cached tutorial or an old SDK example.

A replacement provider is a separate integration decision. Higgsfield publishes a guide about moving to its own developer API; that is a third-party service with its own contract. Pika AI Video is publishing this migration checklist, not offering a public Sora-compatible developer API, API keys, or a drop-in replacement endpoint.

Inventory what your application actually depends on

List every place where the old video integration affects the product. Start with the submit action, then follow a job through waiting, completion, failure, download, and support. Look for assumptions in database columns, background workers, user messages, and billing reconciliation, not only in the API client.

• Inputs: prompt, reference media, output shape, requested duration, and any settings your UI exposes.
• Identity: internal job ID, upstream job ID, requesting user, and the project allowed to access the result.
• Lifecycle: accepted, waiting, running, successful, failed, canceled, and any moderation-specific outcome you need to represent.
• Delivery: polling or webhook behavior, result location, retention period, and who copies the file into durable storage.
• Operations: retry rules, rate limits, cost confirmation, logging, and the way support locates a failed request.

Mark each dependency as required, optional, or removable. If the new provider lacks a required control, that is a product decision to resolve before launch. Renaming a request field cannot make an unsupported capability appear.

Define your own job record before mapping a provider

Keep a stable application job identity and store the provider’s identifier alongside it. For example, a storyboard application can keep its own scene ID even when the upstream provider changes. This prevents a supplier-specific identifier from becoming the only way to find the user’s work.

Build a written mapping from each documented provider response into your application state. Include unknown and malformed responses. Decide how a request that times out during submission is reconciled before it can be retried; otherwise the same user action may create two paid jobs.

For webhooks, confirm authenticity, correlate the event to a known job, and tolerate duplicate or out-of-order delivery. A success event should not overwrite a newer terminal decision without an explicit rule. Use the chosen provider’s current documentation for exact headers, signatures, and retry behavior; this checklist supplies no invented compatibility schema.

Test the migration where the happy path ends

1. Run one small job and confirm that the returned file matches the application job and user.
2. Interrupt polling and resume it without creating a second submission.
3. Replay a completion notification and confirm that delivery and accounting are not repeated.
4. Exercise provider rejection, unavailable output, and a download that fails after generation succeeds.
5. Test cancellation and a late completion arriving during cancellation. Keep the observed outcome instead of guessing which operation won.
6. Confirm that another user cannot inspect or download the job by changing an identifier.

Use provider-supported test facilities or approved small workloads for this validation. Record which checks are simulated and which reached the real service. Passing a mocked response test is useful evidence for an adapter, but it is not proof that credentials, current models, or production billing work.

Plan the cutover and recovery before scaling traffic

Retain the old job records and their provenance while introducing the new provider for a limited approved workload. Separate new submissions from recovery of existing jobs. A provider change must not relabel an old video as a newly generated result.

Define who can stop new submissions, how unfinished jobs are reconciled, and what users see during an interruption. Check the chosen provider’s current rates and storage terms independently. A website subscription, an API balance, and permission to automate are separate matters.