Image-to-Video V2 / Text-to-Video / Omni Reference API Usage

Common Conventions

• All interfaces require request headers Authorization: Bearer <apiKey> and Topview-Uid: <userId>
• Successful response unified structure: { "code": "200", "message": "Success", "result": { ... } }
• After task submission, returns taskId. Frontend polls the query interface to get results

Deprecation Notice: The model display name "Topview Omni" is deprecated and no longer accepted. Please use "Gemini Omni Flash" instead (Image-to-Video, Text-to-Video, and Omni Reference). Requests with the old name will be rejected with: Topview Omni is expired, please use Gemini Omni Flash model.

I. Image-to-Video V2

1.1 Submit Task

POST /v2/common_task/image2video/task/submit

Request Headers

Request Body (JSON)

Supported Models and Parameter Constraints

Note: The model parameter should use the model display name (e.g., "Seedance 2.5"), not the code.

• Image input mode description:
  • Single Image: Only firstFrameFileId takes effect
  • First Frame (End Frame Optional): firstFrameFileId (first frame) is required; endFrameFileId (last frame) is optional
  • Multi-Image (Reference): Pass reference image list via referenceImageFileIds
  • Optional Multi-Image: referenceImageFileIds can be omitted, or pass model-supported image count
• sound: "on" or "off", default "off"; models supporting Native Audio can generate native audio when enabled
• generatingCount: 1–4, default 1
• draftMode: only Seedance 2.5 supports this, default false. When true, the task is generated and billed as a 480p draft, and resolution must be 480. When omitted or false, resolution=480 is still a regular 480p video. Passing true for any other model returns a parameter error

Request Example

POST /v2/common_task/image2video/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.5",
  "firstFrameFileId": "file_abc123",
  "prompt": "A product slowly rotating on a clean white background, cinematic lighting",
  "aspectRatio": "16:9",
  "resolution": 1080,
  "duration": 5,
  "sound": "off",
  "generatingCount": 2
}

Request Example (Seedance 2.5 Draft)

POST /v2/common_task/image2video/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.5",
  "firstFrameFileId": "file_abc123",
  "prompt": "A product slowly rotating on a clean white background, cinematic lighting",
  "resolution": 480,
  "duration": 5,
  "draftMode": true,
  "generatingCount": 1
}

Request Example (Topview T1)

Pass the display name "Topview T1". Do not send aspectRatio or draftMode. Resolution must be 720 or 1080. endFrameFileId and prompt may be omitted. Omitted sound defaults to "on".

POST /v2/common_task/image2video/task/submit
Topview-Uid: user_123

{
  "model": "Topview T1",
  "firstFrameFileId": "file_abc123",
  "endFrameFileId": "file_end456",
  "prompt": "A kitten jumps from the sofa to the floor",
  "resolution": 720,
  "duration": 5,
  "sound": "on",
  "generatingCount": 1
}

Response Example

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_i2v_v2_20250529001",
    "status": "init",
    "boardTaskIds": null,
    "boardId": null,
    "noticeUuid": "uuid_abc"
  }
}

1.2 Query Task Result

GET /v2/common_task/image2video/task/query

Request Parameters

Request Example

GET /v2/common_task/image2video/task/query?taskId=task_i2v_v2_20250529001
Topview-Uid: user_123

Response Example (In Progress)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_i2v_v2_20250529001",
    "status": "running",
    "errorMsg": null,
    "costCredit": "0.00",
    "videos": []
  }
}

Response Example (Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_i2v_v2_20250529001",
    "status": "success",
    "errorMsg": null,
    "costCredit": "5.00",
    "videos": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_video_001",
        "filePath": "https://cdn.example.com/videos/output_001.mp4",
        "width": 1920,
        "height": 1080,
        "duration": 5000,
        "coverPath": "https://cdn.example.com/covers/cover_001.jpg",
        "boardTaskId": null
      },
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_video_002",
        "filePath": "https://cdn.example.com/videos/output_002.mp4",
        "width": 1920,
        "height": 1080,
        "duration": 5000,
        "coverPath": "https://cdn.example.com/covers/cover_002.jpg",
        "boardTaskId": null
      }
    ]
  }
}

II. Text-to-Video

2.1 Submit Task

POST /v1/common_task/text2video/task/submit

Request Headers

Request Body (JSON)

Supported Models and Parameter Constraints

Note: The model parameter should use the model display name (e.g., "Seedance 2.5"), not the code.

• sound: "on" or "off", default "off"; models supporting Native Audio can generate native audio when enabled
• generatingCount: 1–4 (required)
• draftMode: only Seedance 2.5 supports this, default false. When true, the task is generated and billed as a 480p draft, and resolution must be 480. When omitted or false, resolution=480 is still a regular 480p video. Passing true for any other model returns a parameter error

Request Example

POST /v1/common_task/text2video/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.5",
  "prompt": "A futuristic city at night with neon lights reflecting on wet streets, cinematic 4K",
  "aspectRatio": "16:9",
  "resolution": 1080,
  "duration": 5,
  "sound": "on",
  "generatingCount": 1
}

Request Example (Seedance 2.5 Draft)

POST /v1/common_task/text2video/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.5",
  "prompt": "A futuristic city at night with neon lights reflecting on wet streets",
  "aspectRatio": "16:9",
  "resolution": 480,
  "duration": 5,
  "draftMode": true,
  "generatingCount": 1
}

Request Example (Topview T1)

Pass "Topview T1". aspectRatio, resolution, and duration are required. Resolution must be 720 or 1080. Duration is -1 for smart duration, or an integer from 4 through 30. Omitted sound defaults to "on". Do not send draftMode.

POST /v1/common_task/text2video/task/submit
Topview-Uid: user_123

{
  "model": "Topview T1",
  "prompt": "A kitten jumps from the sofa to the floor",
  "aspectRatio": "16:9",
  "resolution": 720,
  "duration": 5,
  "sound": "on",
  "generatingCount": 1
}

Response Example

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2v_20251128001",
    "status": "init",
    "noticeUuid": "uuid_xyz"
  }
}

2.2 Query Task Result

GET /v1/common_task/text2video/task/query

Request Parameters

Request Example

GET /v1/common_task/text2video/task/query?taskId=task_t2v_20251128001
Topview-Uid: user_123

Response Example (Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2v_20251128001",
    "status": "success",
    "errorMsg": null,
    "costCredit": "10.00",
    "videos": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_video_t2v_001",
        "filePath": "https://cdn.example.com/videos/t2v_output_001.mp4",
        "width": 1920,
        "height": 1080,
        "duration": 5000,
        "coverPath": "https://cdn.example.com/covers/t2v_cover_001.jpg"
      }
    ]
  }
}

Response Example (Failure)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_t2v_20251128001",
    "status": "fail",
    "errorMsg": "Model service unavailable",
    "costCredit": "0.00",
    "videos": []
  }
}

III. Omni Reference

Omni Reference supports generating new videos through reference images/videos/audios + prompt. The prompt can reference uploaded materials using the <IMAGEN> / <VIDEON> / <AUDION> syntax.

3.1 Submit Task

POST /v1/common_task/omni_reference/task/submit

Request Headers

Request Body (JSON)

inputImages Object Fields

inputVideos Object Fields

inputAudios Object Fields

Supported Models and Parameter Constraints

Note: The model parameter should use the model display name (e.g., "Seedance 2.5", "Seedance 2.0", "Kling O3 Video-Edit"), not the code.

(Video Edit Mode)

Seedance mixed upload limits:

• Seedance 2.5: maximum 30 images, 10 videos (single video duration 2–30s, total video duration ≤30s), 10 audios (single audio duration 2–30s, total audio duration ≤30s), and maximum 50 total media items. Supports draftMode: when true, the task is generated and billed as a 480p draft, and resolution must be 480. When omitted or false, resolution=480 is still a regular 480p video. Passing true for any other model returns a parameter error
• Seedance 2.0 / Fast / Mini: maximum 9 images, 3 videos (single video duration 2–15.2s, total video duration ≤15.2s), 3 audios (single audio duration 2–15.2s, total audio duration ≤15.2s), and maximum 15 total media items
• Wan 3.0 / Wan 3.0 Prime: maximum 10 images, 5 videos (single video duration 1–15s, total video duration ≤15s), 5 audios (single audio duration 1–15s, total audio duration ≤15s), and maximum 20 total media items
• MiniMax H3 Max: maximum 9 images, 3 videos, 3 audios (single audio duration 2–15s, total audio duration ≤15s), and maximum 12 total media items
• MiniMax H3 Fast: maximum 9 images, 3 videos, 3 audios (single audio duration 2–15s, total audio duration ≤15s), and maximum 15 total media items
• Topview T1: maximum 30 images, 10 videos (single video duration 2–30.2s, total video duration ≤30.2s), 10 audios (wav/mp3, single audio duration 2–30.2s, total audio duration ≤30.2s), and maximum 50 total media items. Prompt is optional. draftMode, internetSearch, videoEditMode, and keepOriginalSound are not supported

Request Example (Topview T1)

Provide at least one of inputImages or inputVideos. aspectRatio, resolution, and duration are required, with the same rules as text-to-video.

POST /v1/common_task/omni_reference/task/submit
Topview-Uid: user_123

{
  "model": "Topview T1",
  "prompt": "Make <IMAGE1> jump from the sofa to the floor",
  "inputImages": [
    {
      "fileId": "file_img_001",
      "name": "Image1"
    }
  ],
  "aspectRatio": "16:9",
  "resolution": 720,
  "duration": 5,
  "generatingCount": 1
}

Vidu Q4 Preview (Video Edit Mode)

Display name Vidu Q4 Preview, code vidu-q4-preview-ref. Prompt is optional. inputVideos is not supported.

Kling (Video Edit Mode)

Kling input video requirements (inputVideos, inputVideoMode: singleVideo):

• Width/Height: 720–2160(4K)px
• Video duration: 3–10 seconds

Grok Video (Video Edit Mode)

Grok input video requirements (inputVideos, inputVideoMode: singleVideo):

• Width/Height: 300–2160(4K)px
• Video duration: 1–15 seconds (Edit) / 2–15 seconds (Extend)
• Do not pass inputImages or internetSearch

Gemini Omni Flash / Happy Horse / Wan 2.7 (Video Edit Mode)

Request Example (Grok Video Edit)

POST /v1/common_task/omni_reference/task/submit
Topview-Uid: user_123

{
  "model": "Grok Video Edit",
  "prompt": "Apply cinematic color grading to <VIDEO1>",
  "inputVideos": [
    {
      "fileId": "file_video_001",
      "name": "Video1"
    }
  ],
  "generatingCount": 1
}

Common parameters description:

• generatingCount: 1–4 (required)
• draftMode: only Seedance 2.5 supports this, default false. When true, resolution must be 480

Request Example (Seedance 2.5 Draft)

POST /v1/common_task/omni_reference/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.5",
  "prompt": "A product slowly rotating, cinematic lighting",
  "aspectRatio": "16:9",
  "resolution": 480,
  "duration": 5,
  "draftMode": true,
  "generatingCount": 1
}

Request Example (Image Reference)

POST /v1/common_task/omni_reference/task/submit
Topview-Uid: user_123

{
  "model": "Kling O3 Video-Edit",
  "prompt": "Transform <IMAGE1> into a watercolor painting style animation with gentle movement",
  "inputImages": [
    {
      "fileId": "file_img_abc001",
      "name": "Image1"
    }
  ],
  "aspectRatio": "16:9",
  "resolution": 720,
  "duration": 5,
  "generatingCount": 1,
  "internetSearch": false
}

Request Example (Image + Video + Audio Mixed Reference)

POST /v1/common_task/omni_reference/task/submit
Topview-Uid: user_123

{
  "model": "Seedance 2.0",
  "prompt": "Apply the style from <IMAGE1> to the motion in <VIDEO1> and sync pacing to <AUDIO1>",
  "inputImages": [
    {
      "fileId": "file_img_style001",
      "name": "Image1"
    }
  ],
  "inputVideos": [
    {
      "fileId": "file_video_motion001",
      "name": "Video1"
    }
  ],
  "inputAudios": [
    {
      "fileId": "file_audio_rhythm001",
      "name": "Audio1"
    }
  ],
  "aspectRatio": "9:16",
  "resolution": 1080,
  "duration": 5,
  "generatingCount": 2
}

Response Example

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_omni_20260302001",
    "status": "init",
    "noticeUuid": "uuid_omni_abc"
  }
}

3.2 Query Task Result

GET /v1/common_task/omni_reference/task/query

Request Parameters

Request Example

GET /v1/common_task/omni_reference/task/query?taskId=task_omni_20260302001
Topview-Uid: user_123

Response Example (Success)

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task_omni_20260302001",
    "status": "success",
    "errorMsg": null,
    "costCredit": "8.00",
    "videos": [
      {
        "status": "success",
        "errorMsg": null,
        "fileId": "file_video_omni_001",
        "filePath": "https://cdn.example.com/videos/omni_output_001.mp4",
        "width": 1920,
        "height": 1080,
        "duration": 5000,
        "coverPath": "https://cdn.example.com/covers/omni_cover_001.jpg",
        "boardTaskId": null
      }
    ]
  }
}

IV. Common Specifications

Task Status Enumeration

Polling Recommendations

Recommended polling interval: 3–5 seconds, timeout should be set to 5 minutes.

Sub-tasks in videos

When generatingCount > 1, the videos list contains multiple sub-task results. Each sub-task has an independent status. When the parent task status=success, all sub-tasks are completed (some sub-tasks may be fail, check the sub-task's status and errorMsg).

Omni Reference Prompt Reference Syntax

Reference input materials in prompt using <IMAGEN>, <VIDEON> or <AUDION>:

"prompt": "Apply the color style from <IMAGE1> to the scene, follow the motion from <VIDEO1>, and align to <AUDIO1> rhythm"

Image1 corresponds to name="Image1" in inputImages, Video1 corresponds to name="Video1" in inputVideos, and Audio1 corresponds to name="Audio1" in inputAudios.

V. Credit Billing Explanation

totalCost = unitCost × generatingCount

unitCost Calculation Rules:

• General Models: Query pricing table using resolution, duration, sound parameters
  • Models with resolution parameter: key = {resolution}_{duration}[_sound], e.g., 1080_10_sound
  • Models without resolution parameter: key = {duration}[_sound], e.g., 10_sound
• Kling O1 Video-Edit (special): unitCost = 0.8 × ceil(input video seconds)
• Grok Video-Edit (special): unitCost = 0.8 × ceil(input video seconds)
• Grok Video (I2V / T2V): unitCost = 0.8 × duration (480p and 720p same rate)

5.1 Model Pricing Tables (Unit: Credits/Generation, generatingCount=1)

Seedance 2.0 / Seedance 2.0 Fast

Billing parameters: resolution, duration

Enabling sound does not add cost. Credit value = per-second rate × duration (seconds).

Image-to-Video / Text-to-Video / Video-Edit (without video input)

Video-Edit (with video input)

Seedance 1.0 Pro Fast / Seedance 1.0 Pro

Billing parameters: resolution, duration (does not support sound)

Kling V3

Billing parameters: resolution, duration, sound Enabling sound: 720p approximately +60%, 1080p approximately +25%

Kling O3 / Kling O3 Reference-to-Video

Billing parameters: resolution, duration, sound Enabling sound approximately +12.5%

Kling 2.6

Billing parameters: duration, sound (no resolution dimension) Enabling sound approximately ×2.1

Kling O1 Reference-to-Video

Billing parameters: duration (1080p only, does not support sound) Approximately 0.5 credits/second

Kling 2.5 Turbo Pro / Kling 2.5 Turbo Std

Billing parameters: duration (1080p only, does not support sound)

Veo 3.1 / Veo 3.1 Reference to video

Billing parameters: resolution, duration, sound 720p and 1080p same price; enabling sound ×2; 2160(4K)p only supports 8s

Veo 3.1 Fast / Veo 3.1 Fast Reference to video

Billing parameters: resolution, duration, sound 720p and 1080p same price; enabling sound approximately +50%; 2160(4K)p only supports 8s

MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3

Billing parameters: resolution, duration (does not support sound) 1080p only supports 6s

MiniMax-Hailuo-2.3-Fast

Billing parameters: resolution, duration (does not support sound) 1080p only supports 6s

Vidu Q4 Preview

Billing parameters: resolution, duration, sound. Enabling sound does not add cost. Image-to-Video is single-image and does not accept aspectRatio. Video Edit uses the same display name Vidu Q4 Preview with code vidu-q4-preview-ref: ratios 9:16, 3:4, 1:1, 4:3, 16:9, duration 3–16s, up to 15 images and 3 mp3 audios (3–12s each), no input video, prompt optional.

Vidu Q3 Pro

Billing parameters: resolution, duration, sound Enabling sound does not add cost; supports 1–16s any duration, linear billing

Vidu Q2 (T2V) / Vidu Q2 Reference to Video (I2V)

Billing parameters: duration (1080p only, does not support sound) I2V Reference mode includes approximately 2.1 credits base cost, same duration approximately ×2 of T2V

Wan 2.6 (I2V and T2V same price)

Billing parameters: resolution, duration, sound Enabling sound does not add cost

Gemini Omni Flash (I2V / T2V / Video Edit)

Billing parameters: resolution, duration (does not support sound)

Gemini Omni 1.1 Flash (I2V / T2V / Video Edit / Reference to video)

Billing parameters: resolution, duration (does not support sound)

MiniMax H3 Max / Max Turbo / Fast (I2V / T2V)

Billing parameters: resolution, duration (I2V / T2V do not support sound)

Video Edit with input video: MiniMax H3 Max is billed at ×2 (480p=1.00, 768p=1.60); MiniMax H3 Fast stays 0.40/sec. Enabling sound does not add cost.

Wan 3.0 Prime (I2V / T2V / Video Edit)

Billing parameters: resolution, duration, and whether the request includes input video

Enabling sound does not add cost.

FLUX 3 Video / FLUX 3 Video Extend

Billing parameters: resolution, duration (enabling sound does not add cost)

Happy Horse 1.0 (I2V / T2V / R2V / Video Edit)

Billing parameters: resolution, duration (does not support sound)

Wan 2.7 (I2V / T2V / R2V / Video Edit / Video Extend)

Billing parameters: resolution, duration (does not support sound)

Wan 2.7 note: Audio upload not supported in API v1.

Topview Series (I2V and T2V same price)

Billing parameters: duration (no resolution, does not support sound)

Kling O3 Video-Edit (Video Edit Mode)

Billing parameters: resolution, output video duration (determined by input video, max 10s, does not support sound)

Kling O1 Video-Edit (Video Edit Mode)

Billing parameters: Input video duration (rounded up per second, does not support sound)

unitCost = 0.8 × ceil(input video seconds)

Grok Video (Image-to-Video / Text-to-Video)

Billing parameters: resolution, duration (480p and 720p same per-second rate; no sound)

unitCost = 0.8 × duration (seconds)

Example: 10s @ 720p → 8.0 credits per generation.

Grok Video Edit / Grok Video Extend (Video Edit Mode)

Billing parameters: Input video duration (rounded up per second)

unitCost = 0.8 × ceil(input video seconds)

5.2 Native Audio (sound) Surcharge Reference