Skip to main content
POST
Start a video, image or motion-control generation
One endpoint for every model in List models. Send the model key and its inputs under their own names; the request is validated against the model, priced live, charged and queued. Poll Poll video status (video and motion control) or Poll image status (image) with generation.id.
  • Price guard: send expectedCredits (for example the quote’s credits). If the live price is higher, nothing is charged and the response is 409 with code PRICE_CHANGED and the new price in credits.
  • Outside media: URLs hosted outside Unsora are copied into your library first, up to 12 per request.
  • Retries: send an Idempotency-Key header so a retried request isn’t charged twice.

Authorizations

Authorization
string
header
required

An Unsora API key (uns_…). A Clerk session token also works.

Headers

Idempotency-Key
string

API key requests only. Retrying with the same key within 24 hours replays the first response (with the Idempotent-Replayed: true header) instead of charging again. The body isn't compared; reusing the key on a different endpoint returns 409 IDEMPOTENCY_CONFLICT. Keys over 128 characters are ignored.

Maximum string length: 128

Body

application/json
model
string
required

Model key from GET /catalog. Older names listed in the model's legacyDbModels (e.g. veo, kling-pro, seedance_2.0) also work. Retired names such as wan, wan_2.6, gpt-image-1.5 and seedream-v5-lite are rejected here; only POST /videos/create and POST /image-generations/create translate them.

Example:

"seedance-2.5"

category
enum<string>

Optional guard: reject the request if the model is from another category.

Available options:
video,
image,
motion-control
mode
string

Mode key from GET /catalog. Omit to pick it from the attached media.

Example:

"omni"

inputs
object

Inputs in the provider's field names, as listed by GET /catalog. Media fields take URLs; files hosted outside Unsora are imported into your library first. Omitted fields use the model's defaults.

Example:
expectedCredits
integer

The most credits you agree to spend (e.g. the quote's credits). If the live price is higher, nothing is charged and the API answers 409 PRICE_CHANGED.

Response

Generation queued

success
boolean
required
generation
object
required
model
string
creditsDeducted
integer
creditsRemaining
integer