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 1.5 pro"), not the code.

• Image input mode description:
  • Single Image: Only firstFrameFileId takes effect
  • First & Last Frame: 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

Request Example

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

{
  "model": "Seedance 1.5 pro",
  "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
}

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 1.5 pro"), not the code.

• sound: "on" or "off", default "off"; models supporting Native Audio can generate native audio when enabled
• generatingCount: 1–4 (required)

Request Example

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

{
  "model": "Seedance 1.5 pro",
  "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
}

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., "Standard", "Kling O3 Video-Edit"), not the code.

(Video Edit Mode)

Seedance 2.0 mixed upload limits:

• Maximum 9 images
• Maximum 3 videos (single video duration: 2–15.2s, total video duration ≤15.2s)
• Maximum 3 audios (single audio duration: 2–15.2s, total audio duration ≤15.2s)
• Images + videos + audios combined cannot exceed 15 items

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)

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": "Standard",
  "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)

Standard / 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.5 pro

Billing parameters: resolution, duration, sound Enabling sound approximately ×2.1

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 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)

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