Recommended Unified Interface Format

Video models usually provide two integration styles: official format and the YutoAPI unified format. For new projects, the unified format is recommended because it normalizes submission, query, status, and result fields across video models. Your frontend and backend only need one task workflow.

Why Use the Unified Format

• Submit tasks with POST /v2/videos/generations.
• Query tasks with GET /v2/videos/generations/{task_id}.
• Use one status set: NOT_START, SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS, FAILURE.
• Read results from data.output or data.outputs, which is easier to download, store, or display.
• Switching models usually only requires changing model and a small number of model-specific parameters.

Best Fit

• You need to integrate multiple video models, such as Seedance, Veo, Grok, Sora, or other video capabilities.
• Your business system needs one structure for task ID, progress, failure reason, and result URL.
• You do not want each client to maintain different status enums and response parsers for each model.
• You want to start with general video generation first, then add official-format advanced parameters only when needed.

If your business must reuse a specific official SDK, official field names, or official callback structure, use that model's official-format page instead.

Unified Format Request Example

Submit a video generation task:

curl --request POST \
  --url '{BaseURL}/v2/videos/generations' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-1-0-pro-250528",
    "prompt": "A detective enters a dim room and checks clues on a desk, cinematic shot, 16:9",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720P"
  }'

Response:

{
  "task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576"
}

Query the task:

curl --request GET \
  --url '{BaseURL}/v2/videos/generations/f186f65a-8657-4e83-b0e3-67facf1b2576' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example completed response:

{
  "task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576",
  "status": "SUCCESS",
  "fail_reason": "",
  "progress": "100%",
  "data": {
    "output": "https://example.com/output.mp4"
  }
}

Image or Video Inputs

The unified format infers the task type from input fields:

• prompt only: text-to-video.
• With images: image-to-video, first-frame video, or reference-image video generation.
• With videos: video-to-video or video editing tasks.

Example:

{
  "model": "doubao-seedance-1-0-pro-250528",
  "prompt": "Make the person walk forward while the camera slowly pushes in",
  "images": ["https://example.com/start-frame.png"],
  "duration": 5,
  "aspect_ratio": "16:9"
}

Unified Format vs Official Format

Format	Recommended use	Related pages
Unified format	Multi-model integration, one task system, lower adaptation cost	Unified Interface Format Introduction
Seedance official format	Existing Volcengine / Seedance official-field integration that must keep official payload structure	Create Task - Official Format, Query - Official Format

Integration Notes

• Store task_id, model, status, progress, fail_reason, and final result URL on your backend.
• Do not block the client while generation runs. Submit the task, then poll the query endpoint.
• Use progressive polling intervals such as 2 seconds, 4 seconds, then 8 seconds.
• Stop polling when status is SUCCESS or FAILURE.
• Do not put API keys in public frontend code, logs, GitHub, or screenshots.