Generation and billing

Request flow

1. GET /api/v1/models gives public preset IDs, scenes, parameters and provider availability.
2. POST /api/v1/quote verifies the input and returns costCredits, remainingCredits and canAfford without creating a task.
3. POST /api/v1/generations requires an Idempotency-Key and maxCostCredits.
4. GET /api/v1/generations/{id} refreshes only a task owned by the authenticated account.
5. GET /api/v1/credits reads the current site-credit balance.

Requests are JSON. presetId is required. scene can be omitted when the model's first supported scene is intended; otherwise choose a scene returned by the model listing. prompt and options must satisfy that model's input contract.

Safe retries

Persist an idempotency key of 1–128 letters, digits, underscores or hyphens before creating a task. Reuse the same key and same request body when a network response is lost. A new key represents a new, chargeable task. Reusing a key with changed inputs returns a conflict.

Do not create a replacement task merely because the original is still processing. Task polling does not create another generation. A 429 response includes Retry-After where available; back off before retrying.

Credit reservations and settlements

A quote is an estimate based on current pricing and verified source media. Generation checks the cost again and refuses a total above maxCostCredits before reserving credits.

Normal tasks charge the configured cost. Layer decomposition reserves the maximum base image plus 16 layers and settles the actual returned output count. Unused reserved credits are returned to their original credit grants once. Check the task's costCredits and billingStatus for the recorded outcome. Provider/content-policy failures can have different refund rules; do not infer a refund solely from an error message.

A successful task includes a taskInfo JSON string with its output images or videos. Save returned files promptly if the storage provider uses expiring URLs. Empty or malformed creative-tool results are treated as failures rather than charged successes.

Reference files

Use directly accessible public media files. Private network addresses, authenticated file pages and unsupported formats are rejected by server-side checks. The studio can normalize supported uploads; API callers must supply valid public files themselves. Inputs are inspected from their bytes, and client-supplied duration or size does not lower the charged cost.

Errors

The API does not accept a caller-supplied user ID, provider credential or callback URL. This release uses owned task polling; external customer webhooks are not exposed. Long-video multi-step orchestration remains available in the studio rather than as one API generation call.