Skip to navigation

Video Generation

Creates an asynchronous video generation task using an OpenAI-compatible request. Applicable model is Doubao-Seedance-2.5; omit model to use auto and let the gateway route within the video generation model pool. Supported modes: text-to-video (prompt required), image-to-video (input_reference as a single image or array, prompt optional), and first-and-last-frame (first_frame / last_frame, prompt optional).

The generation endpoint does not accept input_video; send it here to receive 400 and use POST /openai/v1/videos/edits for multi-video stitching. Up to 30 images (input_reference + first_frame + last_frame combined) may be sent per request.

Returns 202 with a task_id. Fees are pre-deducted at creation and settled on completion based on the upstream output_tokens (overpayment refunded, failure automatically refunded). Poll GET /openai/v1/videos/{task_id} every 3~10 seconds until the task reaches a terminal state (completed / failed). Task records are kept for 24 hours.

Authentication

AuthorizationBearer

Use Authorization: Bearer $JOY_TOKEN_API_KEY.

Request

This endpoint expects an object.
modelstringOptional

Model name, e.g. Doubao-Seedance-2.5. Omit to use auto and let the gateway route within the video generation model pool.

promptstringOptional

Text description. Required for text-to-video; may be omitted when any image input (input_reference / first_frame / last_frame) is present.

sizestringOptional

Resolution/aspect. Accepts 480p / 720p / 1080p or WIDTHxHEIGHT (e.g. 1280x720, converted to the aspect ratio and resolution). Aspect ratios support 16:9 and 9:16; use parameters.aspect_ratio for other ratios.

durationintegerOptional

Video length in seconds. Continuous 2~30 range (Seedance 2.5), default 8. Out-of-range values are clamped (<2 becomes 2, >30 becomes 30). Stitch longer videos through POST /openai/v1/videos/edits.

input_referencestring or list of stringsOptional

Reference image URL(s). A single string is one image; an array is multiple images for multi-subject reference (each sent with the reference_image role). Up to 30 images per request (input_reference + first_frame + last_frame combined), otherwise 400.

first_framestringOptionalformat: "uri"

First-frame image URL (first_frame role).

last_framestringOptionalformat: "uri"

Last-frame image URL (last_frame role).

userstringOptional

Optional end-user identifier for abuse tracking.

parametersobjectOptional

Native upstream parameter passthrough; snake_case field names are preferred (camelCase accepted). Supports aspect_ratio, resolution, duration_seconds, generate_audio, seed, negative_prompt, compression_quality, and person_generation. fps, sample_count, and 4K resolutions are not supported (rejected or ignored). Top-level duration / size explicitly provided take precedence.

Response

Task accepted. Fees are settled on task completion based on actual usage.
task_idstring
Task id used for polling and download.
statusenum
Always processing on creation.
Allowed values:
progressinteger
Progress percentage, always 0 on creation.
modelstring

The actually selected model name (the real model after auto routing).

createdlong

Unix timestamp (seconds) of task creation.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
502
Bad Gateway Error
503
Service Unavailable Error