Migrate a provider-specific script to OfflineCreator REST

Translate the workflow, not the provider's field names

Treat this migration as a contract rewrite. The published OfflineCreator 0.1.2 client sends a personal API key as an `Authorization: Bearer` header to an HTTPS Studio origin and restricts requests to `/api/v1/*`. Its generation call accepts `modelId`, `prompt`, and an optional `aspectRatio`; the same client exposes separate model-catalog, credit-balance, generation-list, status, cancel, input-upload, and submit operations. Start by listing models and selecting a Studio model ID rather than copying a provider endpoint string into `modelId`.

Build an adapter at the edge of the existing script, but do not assume the creation response contains `generationId`. The published declaration types creation only as `Promise<Record<string, unknown>>`, while later status, cancel, input, submit, and wait methods require the caller to supply an identifier. Inspect the actual authenticated creation response and extract an identifier only when its current documentation or returned shape establishes the field and value; otherwise record the missing identifier contract as a blocking evidence gap. The declarations separately document `16:9`, `9:16`, and `1:1` for aspect ratio and PNG, JPEG, WebP, or GIF for an uploaded image.

Authentication

Studio Bearer API keyReplace a provider-specific key and header scheme with a scoped OfflineCreator personal key held in secret configuration.

Model selection

Catalog result to Studio modelIdResolve the destination ID from the authenticated model catalog; do not infer it from a provider slug.

Job identity

Verify before extractingCreation returns an unspecified record in the declaration. Later operations accept a caller-supplied generationId, but the cited contract does not guarantee where that ID originates.

Compare the current REST contracts before changing code

The two contracts are not interchangeable. OfflineCreator's published client uses one Studio API origin and resource-oriented `/api/v1` paths. It sends creation to `POST /api/v1/generations`, but the declaration promises only an unspecified record in response. Separate status, input, submit, and cancel methods require a caller-supplied `generationId`; the input method uploads binary image bytes and submit is a distinct operation. The client recognizes `completed` and `failed` as terminal states and can convert a same-origin Studio output URL, but these later operations do not prove that creation returns their required identifier.

Direct fal is a concrete provider-specific counterexample, not a description of every provider. Its current queue documentation submits to a model endpoint at `queue.fal.run`, authenticates with `Authorization: Key`, returns `request_id` plus response, status, and cancel URLs, and reports `IN_QUEUE`, `IN_PROGRESS`, and `COMPLETED`. fal also says final result structures are model-specific. A fal script therefore needs explicit mappings for authentication, model path, identifier name, uppercase queue states, result envelope, cancellation semantics, and any webhook branch; changing only the hostname would be incorrect.

OfflineCreator

Studio generation resourceLater status, upload, submit, cancellation, and wait operations accept a generationId supplied by the caller; creation's declared record does not guarantee that field.

Direct fal example

Model queue requestA request ID and operation URLs link queue status, response retrieval, cancellation, and optional webhook delivery.

Parity rule

Map semantics one field at a timeRecord unsupported inputs, state distinctions, logs, metrics, webhooks, and result fields as explicit gaps.

Cut over with a reversible adapter

First, capture one sanitized request fixture from the old script: intent, provider model, prompt, dimensions or aspect ratio, optional image, provider-only parameters, completion handling, and expected artifact type. Do not copy credentials, signed URLs, or customer media into the fixture. Query OfflineCreator's authenticated model catalog, choose the intended Studio model, and create a reviewed mapping from the old model name to the returned `modelId`.

Second, replace the submit boundary. Send JSON with the mapped `modelId`, prompt, and a supported aspect ratio, then inspect the actual authenticated response. Do not assume an identifier field: the declaration promises only a record of unknown values. Extract and store an identifier only if current documentation or the observed response establishes it. If neither does, stop before polling and record the workflow as blocked. When the migration deliberately chooses the documented image-input path, use a validated caller-supplied identifier to upload image bytes and then call the separate submit operation; do not infer that choice from an undocumented response flag.

Third, run the old and new adapters behind a dry selection switch. Compare control flow and required fields, not image quality or latency unless you conduct a separate matched test. Before retiring the old path, verify authenticated model lookup, the real creation-response shape, the documented source of any later-operation identifier, insufficient-credit handling, the explicitly chosen image-input path when needed, a terminal failure, a completed result, retrieval through the package's short-lived signed-URL operation, and restart recovery. Keep provider-specific code available for rollback until those acceptance cases pass.

Do not carry provider assumptions across the boundary

Authentication is the first common failure. fal documents `Authorization: Key $FAL_KEY`, while OfflineCreator's published package documents a Studio personal API key and sends it as `Authorization: Bearer`. The published client refuses its ordinary request path when neither an API key nor an authorized fetcher is configured. Use a scoped key from Studio settings, confirm catalog and balance responses separately, and never translate a provider key into the new header.

Lifecycle mismatch is the second. fal's queue documentation supports polling with optional runner logs and a server-sent-event stream whose events use the queue status shape. Its webhook documentation describes retry delivery and asks receivers to use `request_id` for idempotency. OfflineCreator's published 0.1.2 client instead implements bounded polling and only treats `completed` and `failed` as terminal. Do not retain a fal status stream or webhook endpoint and assume Studio will call it; keep an explicit Studio polling worker unless a separate current Studio contract documents another callback.

Billing and output assumptions are the third. OfflineCreator states that API, CLI, MCP, and web generations share the Studio account credit balance and published per-model costs, that the selected cloud provider is disclosed, and that failed jobs refund credits automatically. Those are first-party product statements, not an independent billing audit. This research did not make an authenticated generation, test a refund, compare provider prices, measure latency, or establish output equivalence.

Use a parity ledger as the release gate

Create one row for every behavior the old script depends on. Mark it mapped only when the destination request, response, and failure behavior are observed or supported by the cited contract. Mark it intentionally removed when the team accepts the loss. Keep the migration blocked when a provider-only parameter, webhook dependency, result field, cancellation guarantee, or artifact-retention assumption has no verified Studio equivalent.

This ledger prevents a successful HTTP response from being mistaken for a complete migration. The published contracts establish meaningful differences: Studio exposes a normalized generation resource and a narrow request type, while fal exposes queue-specific states, operation URLs, logs and metrics, optional webhooks, and model-specific result bodies. The sources do not establish feature-for-feature parity, equivalent quality, equivalent cost, equivalent timing, or identical cancellation after processing starts.

Ready

Mapped and acceptance-testedAuthentication, model ID, request fields, status, failure, output, billing precheck, and restart behavior all have evidence.

Conditional

Supported with a workflow changeFor example, replace a webhook consumer with bounded polling and record the operational consequence.

Blocked

No verified destination behaviorRetain the provider adapter or remove the dependency explicitly; never infer parity.

Choose the next page by the unresolved boundary

Use the billing comparison when account ownership, prepaid balances, or invoice consolidation drives the migration. Use the polling comparison when the old script depends on callbacks or long-running queue behavior. Return to the comparison directory when the unresolved choice is REST, MCP, CLI, or a direct provider integration rather than a code-level mapping.

Evidence boundary and remaining gaps

This page owns the migration contract from a provider-specific media script to OfflineCreator REST. It does not claim universal provider parity, benchmark output quality, compare every provider, document an OpenAPI schema, or promise that undocumented fields and callbacks exist. Its REST details are limited to the cited immutable `@offlinecreator/mcp` 0.1.2 client, declarations, and MCP server tool descriptions; billing, provider-disclosure, and private media-delivery statements are limited to the cited package record and current first-party product page. Refresh those sources on the monthly cadence.

This draft records degraded recent-source coverage and insufficient community evidence. The mandatory last30days run returned 58 items, but none entered the claim ledger as relevant OfflineCreator REST migration evidence. No community source is used in the claim ledger, and no practitioner outcome is asserted. Adoption, migration outcomes, client compatibility, reliability, performance, and customer sentiment remain evidence gaps rather than negative findings.