Video Generation API: Async Text-to-Video Endpoint

Choose a request shape

The unified endpoint covers common video workflows. Choose fields by input type, then verify that the selected model supports that capability.

Goal	Key fields	Use when
Text to video	model + prompt	Generate from a prompt only
Single image to video	image	Animate one source image
Multiple references	images[]	Constrain character, outfit, or setting separately
First/last-frame interpolation	first_frame + last_frame	Fix both the opening and closing frame
Video editing	video + images[]	Replace elements or transfer style with instructions
new-api-compatible call	seconds + size + images	Keep existing new-api client fields

Every row above uses the client-facing unified API. To preserve provider-native content, roles, or newly released parameters, use the matching native passthrough endpoint and treat the provider's official docs as the field contract.

Two-step asynchronous flow

Submit: POST /v1/videos immediately returns an id with queued status.
Poll: call GET /v1/videos/{id} every few seconds until the status becomes completed or failed.
Download: after completion, call GET /v1/videos/{id}/content for the result.

API-key calls reserve the estimated cost at submission and settle the actual result on success. Failure or timeout releases the reservation. Settlement and release are idempotent, so repeated polling never charges twice.

Submission parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The video model. See available models below.

Example:your-video-model-id

promptstringRequired

A description of the video to generate.

Example:A shiba inu running through a field, cinematic lighting

imagestring | string[]Optional

One reference image as a public URL or data URI. string[] is accepted for compatibility, but use images for multiple references.

Example:https://.../reference.png

imagesstring[]Optional

Multiple reference images. Array order defines image 1, image 2, and so on. Public URLs and data URIs are accepted.

Example:["https://.../person.png","https://.../scene.png"]

first_framestringOptional

First keyframe URL for image-to-video or first/last-frame interpolation.

Example:https://.../first.png

last_framestringOptional

Last keyframe URL, normally used together with first_frame.

Example:https://.../last.png

videostringOptional

Public source-video URL for video editing. Providing it automatically selects video_edit mode. video_url is accepted as an alias.

Example:https://.../source.mp4

reference_videostring | string[]Optional

One reference-video URL or an array, available only on models with multimodal reference support.

Example:https://.../motion.mp4

reference_audiostring | string[]Optional

One reference-audio URL or an array. Audio cannot be used alone; include a reference image or video.

Example:https://.../voice.mp3

durationintegerOptional

Video duration in seconds. Supported values depend on the model.

Example:5

resolutionstringOptional

Output resolution such as 720P or 1080P.

Example:720P

aspect_ratiostringOptional

Aspect ratio such as 16:9, 9:16, or 1:1.

Example:16:9

bitrate_modestringOptional

Seedance output bitrate mode. Supported values are standard and high; omitted values use the model default, then the upstream default when unconfigured.

Example:standard

negative_promptstringOptional

Content to avoid. It only affects models that support negative prompts.

Example:blur, camera shake, text watermark

seedintegerOptional

Random seed. A fixed seed helps reproduce experiments, but exact output is not guaranteed across models or upstream versions.

Example:123456

enable_audiobooleanOptional

Whether to generate audio. Enabled by default: omit to keep it on, or pass false to disable. The alias generate_audio is also accepted (enable_audio wins if both are set). Whether the result actually has sound also depends on the selected model supporting audio.

Example:true

audio_settingstringOptional

Audio policy for video editing: auto lets the model decide, while origin preserves the source video's audio.

Example:origin

Image-to-video and multiple references (unified format)

Use image for one reference and images for multiple references. In the prompt, bind their purposes by array order as image 1, image 2, and so on. Use first_frame and last_frame for keyframes; do not put a native Volcano content array directly at the top level of this site's /v1/videos request.

One reference · image to video

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Have the person turn and walk toward the window while the camera slowly pushes in",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9"
  }'

Multiple references · reference to video

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Use image 1 for the character, image 2 for the outfit, and image 3 for the setting, then create a cinematic chase shot",
    "images": [
      "https://example.com/person.png",
      "https://example.com/outfit.png",
      "data:image/png;base64,..."
    ],
    "duration": 5,
    "resolution": "1080P",
    "aspect_ratio": "16:9",
    "enable_audio": true
  }'

Reference count, file size, roles, and video/audio support depend on the selected model. The unified endpoint does not accept a role per image. Use the dedicated keyframe fields, or use the provider's native passthrough endpoint and official documentation for provider-specific roles.

HappyHorse video editing

happyhorse-1.0-video-edit takes exactly one source video and up to five reference images for instruction-driven replacement or global style transfer.

Source video + reference image · edit

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "Replace the person's jacket with the striped jacket from image 1 while preserving the original motion and camera work",
    "video": "https://example.com/source.mp4",
    "images": ["https://example.com/striped-coat.png"],
    "resolution": "1080P",
    "audio_setting": "origin",
    "seed": 123456
  }'

The source must be a publicly accessible MP4 or MOV URL. Output length follows the source (only the first 15 seconds are used), so duration and aspect_ratio are not sent to this model. Successful tasks settle against the actual usage.duration returned by Model Studio.

new-api-compatible client requests

Clients may call the same /v1/videos endpoint directly with new-api's generic video-task shape; no additional gateway is required. model, prompt, image, images, and mode work directly, while the aliases below are normalized into the unified task.

Call this site directly · new-api format

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Use the character in image 1 and the setting in image 2 to create a cinematic shot",
    "seconds": "5",
    "size": "1920x1080",
    "images": [
      "https://example.com/person.png",
      "https://example.com/location.png"
    ],
    "metadata": {
      "client_job_id": "order-20260809-001"
    }
  }'

Compatible fields

secondsinteger | stringOptional

Video duration as a positive integer or numeric string. It is an alias for duration and takes precedence when both are present.

Example:5

sizestringOptional

Output dimensions in WxH form. The service derives the resolution tier and aspect ratio from this value.

Example:1920x1080

input_referencestring | objectOptional

One reference image as a URL/data URI string or an object containing image_url.

Example:https://.../reference.png

metadataobject | JSON stringOptional

Caller-defined business metadata as a JSON object or an encoded JSON string. It is returned unchanged when the task is queried.

Example:{"client_job_id":"order-001"}

metadata stores business data and does not replace generation parameters. Direct clients should use size or top-level resolution/aspect_ratio for dimensions and top-level enable_audio/generate_audio for audio. Use /ark and the official provider docs for native Volcano content and roles.

Retrieve a task

GET/v1/videos/{id}

The response is an OpenAI Videos-compatible object with one of four statuses: queued, in_progress, completed, or failed. Terminal results are cached, so repeated retrieval does not call the upstream again. progress is a stage indicator, not frame-level upstream progress.

status	progress	Meaning
queued	0	The task was accepted and is waiting for upstream processing.
in_progress	50	The upstream is generating or the platform is processing the result.
completed	100	The task completed. metadata.url is a compatibility extension; the content endpoint is also available.
failed	100	The task failed. error.message contains the public failure reason.

Download the result

GET/v1/videos/{id}/content

The content endpoint responds with a 307 redirect to the currently available media URL. Clients must follow redirects and send the Authorization required for the request to this site.

③ Download

curl -L https://zerofa.ai/v1/videos/<task-id>/content \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  --output result.mp4

Use the content endpoint as the stable application integration point rather than persisting the domain or query string from metadata.url. Media URLs are normally short-lived signed links; download the file to your own storage for long-term retention.

Available models

Loading…

See video models in the Model Catalog and filter for Video. Billing is duration in seconds multiplied by the model price.

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

① Submit

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "A shiba inu running through a field, cinematic lighting",
    "duration": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9",
    "enable_audio": true
  }'
# → {"id":"<task-id>","object":"video","status":"queued",
#    "progress":0,"seconds":"5","size":"1280x720"}

② Poll

curl https://zerofa.ai/v1/videos/<task-id> \
  -H "Authorization: Bearer sk-zerofa-xxx"

# queued      → {"id":"...","status":"queued","progress":0}
# in_progress → {"id":"...","status":"in_progress","progress":50}
# completed   → {"id":"...","status":"completed","progress":100,
#                "metadata":{"url":"https://.../result.mp4"}}

Choose a request shape

The unified endpoint covers common video workflows. Choose fields by input type, then verify that the selected model supports that capability.

Goal	Key fields	Use when
Text to video	model + prompt	Generate from a prompt only
Single image to video	image	Animate one source image
Multiple references	images[]	Constrain character, outfit, or setting separately
First/last-frame interpolation	first_frame + last_frame	Fix both the opening and closing frame
Video editing	video + images[]	Replace elements or transfer style with instructions
new-api-compatible call	seconds + size + images	Keep existing new-api client fields

Two-step asynchronous flow

Submit: POST /v1/videos immediately returns an id with queued status.
Poll: call GET /v1/videos/{id} every few seconds until the status becomes completed or failed.
Download: after completion, call GET /v1/videos/{id}/content for the result.

Submission parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The video model. See available models below.

Example:your-video-model-id

promptstringRequired

A description of the video to generate.

Example:A shiba inu running through a field, cinematic lighting

imagestring | string[]Optional

One reference image as a public URL or data URI. string[] is accepted for compatibility, but use images for multiple references.

Example:https://.../reference.png

imagesstring[]Optional

Multiple reference images. Array order defines image 1, image 2, and so on. Public URLs and data URIs are accepted.

Example:["https://.../person.png","https://.../scene.png"]

first_framestringOptional

First keyframe URL for image-to-video or first/last-frame interpolation.

Example:https://.../first.png

last_framestringOptional

Last keyframe URL, normally used together with first_frame.

Example:https://.../last.png

videostringOptional

Public source-video URL for video editing. Providing it automatically selects video_edit mode. video_url is accepted as an alias.

Example:https://.../source.mp4

reference_videostring | string[]Optional

One reference-video URL or an array, available only on models with multimodal reference support.

Example:https://.../motion.mp4

reference_audiostring | string[]Optional

One reference-audio URL or an array. Audio cannot be used alone; include a reference image or video.

Example:https://.../voice.mp3

durationintegerOptional

Video duration in seconds. Supported values depend on the model.

Example:5

resolutionstringOptional

Output resolution such as 720P or 1080P.

Example:720P

aspect_ratiostringOptional

Aspect ratio such as 16:9, 9:16, or 1:1.

Example:16:9

bitrate_modestringOptional

Seedance output bitrate mode. Supported values are standard and high; omitted values use the model default, then the upstream default when unconfigured.

Example:standard

negative_promptstringOptional

Content to avoid. It only affects models that support negative prompts.

Example:blur, camera shake, text watermark

seedintegerOptional

Random seed. A fixed seed helps reproduce experiments, but exact output is not guaranteed across models or upstream versions.

Example:123456

enable_audiobooleanOptional

Example:true

audio_settingstringOptional

Audio policy for video editing: auto lets the model decide, while origin preserves the source video's audio.

Example:origin

Image-to-video and multiple references (unified format)

One reference · image to video

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Have the person turn and walk toward the window while the camera slowly pushes in",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9"
  }'

Multiple references · reference to video

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Use image 1 for the character, image 2 for the outfit, and image 3 for the setting, then create a cinematic chase shot",
    "images": [
      "https://example.com/person.png",
      "https://example.com/outfit.png",
      "data:image/png;base64,..."
    ],
    "duration": 5,
    "resolution": "1080P",
    "aspect_ratio": "16:9",
    "enable_audio": true
  }'

HappyHorse video editing

happyhorse-1.0-video-edit takes exactly one source video and up to five reference images for instruction-driven replacement or global style transfer.

Source video + reference image · edit

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "Replace the person's jacket with the striped jacket from image 1 while preserving the original motion and camera work",
    "video": "https://example.com/source.mp4",
    "images": ["https://example.com/striped-coat.png"],
    "resolution": "1080P",
    "audio_setting": "origin",
    "seed": 123456
  }'

new-api-compatible client requests

Call this site directly · new-api format

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "Use the character in image 1 and the setting in image 2 to create a cinematic shot",
    "seconds": "5",
    "size": "1920x1080",
    "images": [
      "https://example.com/person.png",
      "https://example.com/location.png"
    ],
    "metadata": {
      "client_job_id": "order-20260809-001"
    }
  }'

Compatible fields

secondsinteger | stringOptional

Video duration as a positive integer or numeric string. It is an alias for duration and takes precedence when both are present.

Example:5

sizestringOptional

Output dimensions in WxH form. The service derives the resolution tier and aspect ratio from this value.

Example:1920x1080

input_referencestring | objectOptional

One reference image as a URL/data URI string or an object containing image_url.

Example:https://.../reference.png

metadataobject | JSON stringOptional

Caller-defined business metadata as a JSON object or an encoded JSON string. It is returned unchanged when the task is queried.

Example:{"client_job_id":"order-001"}

Retrieve a task

GET/v1/videos/{id}

status	progress	Meaning
queued	0	The task was accepted and is waiting for upstream processing.
in_progress	50	The upstream is generating or the platform is processing the result.
completed	100	The task completed. metadata.url is a compatibility extension; the content endpoint is also available.
failed	100	The task failed. error.message contains the public failure reason.

Download the result

GET/v1/videos/{id}/content

The content endpoint responds with a 307 redirect to the currently available media URL. Clients must follow redirects and send the Authorization required for the request to this site.

③ Download

curl -L https://zerofa.ai/v1/videos/<task-id>/content \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  --output result.mp4

Available models

Loading…

See video models in the Model Catalog and filter for Video. Billing is duration in seconds multiplied by the model price.

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

① Submit

curl https://zerofa.ai/v1/videos \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model-id",
    "prompt": "A shiba inu running through a field, cinematic lighting",
    "duration": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9",
    "enable_audio": true
  }'
# → {"id":"<task-id>","object":"video","status":"queued",
#    "progress":0,"seconds":"5","size":"1280x720"}

② Poll

curl https://zerofa.ai/v1/videos/<task-id> \
  -H "Authorization: Bearer sk-zerofa-xxx"

# queued      → {"id":"...","status":"queued","progress":0}
# in_progress → {"id":"...","status":"in_progress","progress":50}
# completed   → {"id":"...","status":"completed","progress":100,
#                "metadata":{"url":"https://.../result.mp4"}}

Generate video (async)

Choose a request shape

Two-step asynchronous flow

Submission parameters

Image-to-video and multiple references (unified format)

HappyHorse video editing

new-api-compatible client requests

Retrieve a task

Download the result

Available models

Request and response bodies

Generate video (async)

Choose a request shape

Two-step asynchronous flow

Submission parameters

Image-to-video and multiple references (unified format)

HappyHorse video editing

new-api-compatible client requests

Retrieve a task

Download the result

Available models

Request and response bodies