DocsAPI referenceCreate a job

Create a job

Asynchronous: returns a job id to poll. Same body for video and image, without duration for images.

Submit a generation job. Use /v1/videos for video and /v1/images for images — same body, without duration. The call is asynchronous and returns a job id to poll.

POST/v1/videos

POST/v1/images

POST/v1/videosVideo generation

POST/v1/imagesImage generation

Headers

X-API-Keystringrequired

Your usz_ key. Invalid or revoked keys return 401 invalid_api_key.

Idempotency-Keystringrequired

Unique per request. Reusing it returns the original job.

X-API-Keystringrequired

Your usz_ API key. Missing, malformed or revoked keys return 401 invalid_api_key.

Content-Typestringrequired

Must be application/json, otherwise 415 unsupported_media_type.

Idempotency-Keystringrequired

1–200 characters, unique per distinct request. Reusing it returns the original job; a different body returns 409.

Body

modelstringrequired

Model alias, e.g. seedance-2.5-v5.

promptstringrequired

Up to 4,000 characters on V5 (15,000 on seedance-2.5-v5).

resolutionstringrequired

720p on seedance-2.5-v5 today.

durationintegerrequired

Video only. Whole seconds the model lists.

image_refsstring[]optional

Base64 data URLs — up to 9 on V5, 10 on V7.

modelstringrequired

Model alias, e.g. seedance-2.5-v5. Coming-soon models return 422 model_unavailable.

promptstringrequired

What to generate. Up to 4,000 characters on V5 (15,000 on seedance-2.5-v5).

resolutionstringrequired

One of the model’s sellable resolutions — 720p on seedance-2.5-v5 today.

durationintegerrequired

Video only. Whole seconds within the model’s range — 4–30 on seedance-2.5-v5.

aspectstringoptional

One of the model’s aspect ratios (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Defaults to the first.

start_framestring (data URL)optional

V5 video only. First frame for image-to-video, as a base64 data URL.

image_refsstring[]optional

Reference images as base64 data URLs — up to 9 on V5, up to 10 on V7.

Example

curl -X POST $API/v1/videos \
  -H "X-API-Key: $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"seedance-2.5-v5",
    "prompt":"calm lake at dawn",
    "resolution":"720p", "duration":10}'

curl -X POST https://api.userize.site/v1/videos \
  -H "X-API-Key: usz_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9c1e2a-4b7d-4c2e-9a1f" \
  -d '{
    "model": "seedance-2.5-v5",
    "prompt": "a calm mountain lake at dawn",
    "resolution": "720p",
    "duration": 10,
    "aspect": "16:9"
  }'

202 Acceptedapplication/json

{
  "job_id": "0f149db4-ecea-4104-ae41-5eb63a5bdd17",
  "status": "queued"
}

402 Payment Requiredapplication/json

{
  "error": { "code": "insufficient_credits", "message": "Insufficient credits" }
}

Submit errors

CodeHTTPMeaning

invalid_api_key401Missing, malformed or revoked API key.

validation_error422A field is missing or invalid (model, prompt, resolution, duration, aspect).

price_unavailable422No active price tier for that resolution and duration.

insufficient_credits402Balance is below the job price.

too_many_concurrent429This key already has 25 image jobs queued or running.

idempotency_conflict409Idempotency-Key reused with a different request body.

invalid_api_key

Missing, malformed or revoked key

401

validation_error

A field is missing or invalid

422

insufficient_credits

Balance is below the job price

402

too_many_concurrent

25 image jobs already in flight

429

idempotency_conflict

Key reused with a different body

409