Seedance 2.0 Reference to Video API Documentation

Generate video content using the seedance-2.0-reference-to-video model

Overview

This document describes how to use the seedance-2.0-reference-to-video model for reference-guided video generation.

The integration flow consists of two steps:

1. Create a generation task
2. Query task status and results

Authentication

All API requests require a Bearer Token in the request header:

Authorization: Bearer YOUR_API_KEY

Get API Key:

1. Open the API Keys page
2. Click Create API Key
3. Add the key to the request header: Authorization: Bearer YOUR_API_KEY

1. Create Generation Task

API Information

• URL: POST https://aigptimage.com/api/v1/jobs/createTask
• Content-Type: application/json

Request Parameters

Model Parameter

The model parameter specifies which public reference-to-video model to use.

Note: The model value must match exactly and use the public model ID shown on this page.

input Object Parameters

prompt

• Type: string
• Required: No
• Description: Prompt describing the target video and how the references should be used
• Max Length: 20000 characters

reference_image_urls

• Type: string[]
• Required: No
• Description: Reference image URLs used for subject, style, or scene guidance

reference_video_urls

• Type: string[]
• Required: No
• Description: Reference video URLs used for motion, camera language, or rhythm guidance

reference_audio_urls

• Type: string[]
• Required: No
• Description: Reference audio URLs used for timing or soundtrack guidance

aspect_ratio

• Type: string
• Required: No
• Description: Convenience field accepted by the public API and internally mapped to ratio
• Common Options: 16:9, 9:16, 1:1, 3:4

ratio

• Type: string
• Required: No
• Description: Output video ratio. If both ratio and aspect_ratio are provided, ratio takes priority
• Common Options: 16:9, 9:16, 1:1, 3:4

resolution

• Type: string
• Required: No
• Description: Output resolution used for generation and billing
• Options: 480p, 720p, 1080p

duration

• Type: number
• Required: No
• Description: Video duration in seconds

generate_audio

• Type: boolean
• Required: No
• Description: Whether to generate audio for the output video
• Default Value: false

web_search

• Type: boolean
• Required: No
• Description: Whether to enable web search assistance before generation
• Default Value: false

nsfw_checker

• Type: boolean
• Required: No
• Description: Controls platform-side content filtering for the generated result
• Default Value: false
• Behavior: If set to false, platform-side content filtering is disabled and the model result is returned directly

Credit Consumption

The current public credit rule for seedance-2.0-reference-to-video is:

Request Example

{
  "model": "seedance-2.0-reference-to-video",
  "input": {
    "prompt": "Use the reference images for character identity and the reference video for camera rhythm. Generate a dramatic training sequence with fast movement and cinematic lighting.",
    "reference_image_urls": ["https://cdn.example.com/ref-1.png"],
    "reference_video_urls": ["https://cdn.example.com/ref-motion.mp4"],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "nsfw_checker": false
  }
}

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxxxxxxxxxxxx"
  }
}

Response Parameters

2. Query Task Status

API Information

• URL: GET https://aigptimage.com/api/v1/jobs/recordInfo
• Parameter: taskId (URL query parameter)

Request Example

GET https://aigptimage.com/api/v1/jobs/recordInfo?taskId=task_xxxxxxxxxxxxx

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxxxxxxxxxxxx",
    "model": "seedance-2.0-reference-to-video",
    "state": "waiting",
    "param": "{\"model\":\"seedance-2.0-reference-to-video\",\"input\":{\"prompt\":\"Use the reference images for character identity and the reference video for camera rhythm. Generate a dramatic training sequence with fast movement and cinematic lighting.\",\"reference_image_urls\":[\"https://cdn.example.com/ref-1.png\"],\"reference_video_urls\":[\"https://cdn.example.com/ref-motion.mp4\"],\"ratio\":\"16:9\",\"resolution\":\"720p\",\"duration\":5}}",
    "resultJson": null,
    "failCode": null,
    "failMsg": null,
    "costTime": null,
    "completeTime": null,
    "createTime": 1757584164490
  }
}

Success Result Structure

For reference-to-video tasks, resultJson usually has this structure when the task succeeds:

{
  "resultUrls": ["https://your-cdn.example.com/result-1.mp4"]
}

Usage Flow

1. Prepare public reference file URLs
2. Call POST /api/v1/jobs/createTask
3. Extract taskId from the response
4. Poll GET /api/v1/jobs/recordInfo?taskId=...
5. Read output video URLs from resultJson when the task succeeds

Notes

• API calls use the same credit balance and billing rules as the web app
• Reference images, videos, and audio should be public URLs that your backend can safely send to the API
• resolution, duration, and audio settings affect credit consumption

Error Codes