Overview

Video Recast creates a new video from a source video and reference images using Seedance 2.5. Two modes are available:

Before you start

1. Authenticate with Authorization: Bearer <your-api-key> and Topview-Uid: <your-topview-uid>. See Authentication.
2. Create or select a Board that your account can edit using the Board API. Its ID is required for submission.
3. Upload the source video and reference images using the Upload API and complete the upload check. Supply the returned fileId values, not URLs.
4. Use a source video between 4 and 30 seconds. Its encoded width × height must not exceed 8,295,044 pixels. Supply its actual duration in seconds.

Submit task

POST https://api.topview.ai/v1/common_task/video_recast/task/submit

Content type: application/json.

Reference images are named Image1, Image2, etc. in array order. The source video is named Video1. Wrap each reference name in three opening angle brackets and three closing angle brackets (case-sensitive). Use the literal reference markers shown in the JSON example below. Replace the placeholder IDs with your own Board and uploaded file IDs before submitting. The model is fixed; there is no model-selection parameter.

Example: motion transfer with inferred prompt

curl --request POST \
  --url https://api.topview.ai/v1/common_task/video_recast/task/submit \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Topview-Uid: <your-topview-uid>" \
  --header "Content-Type: application/json" \
  --data '{
    "boardId": "<editable-board-id>",
    "mode": "motionTransfer",
    "videoFileId": "<uploaded-video-file-id>",
    "sourceDuration": 10.08,
    "referenceImageFileIds": ["<uploaded-subject-image-file-id>"],
    "resolution": 720
  }'

Example: element replacement

Use the same endpoint and headers with this request body:

{
  "boardId": "<editable-board-id>",
  "mode": "objectSwap",
  "videoFileId": "<uploaded-video-file-id>",
  "sourceDuration": 7.07,
  "referenceImageFileIds": [
    "<uploaded-bottle-image-file-id>",
    "<uploaded-cat-image-file-id>"
  ],
  "resolution": 720,
  "prompt": "Replace the dog in <<<Video1>>> with the cat in <<<Image2>>> and the bottle with <<<Image1>>>. Preserve the original actions and camera."
}

Submit response

The response uses the standard API envelope. Check code for success (200). The following illustrates its result object:

{
  "taskId": "<board-task-id>",
  "status": "running",
  "boardId": "<editable-board-id>",
  "boardTaskIds": ["<board-task-id>"]
}

Save result.taskId and use it for all subsequent queries. This is the Board task ID, not an internal generation task ID. A successful submission means the task was accepted, not that generation has finished.

Query task

GET https://api.topview.ai/v1/common_task/video_recast/task/query

curl --request GET \
  --url "https://api.topview.ai/v1/common_task/video_recast/task/query?taskId=<board-task-id>" \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Topview-Uid: <your-topview-uid>"

Poll while the task is running. Generation includes preparation and may include restoration of the source audio after video generation. Wait for the complete task to report success; an intermediate video is not the final result. Stop polling on a terminal failure and inspect errorCode and errorMsg.

Query response

The response uses the standard API envelope. Its result contains:

Illustrative successful query payload (the outer API envelope is omitted):

{
  "taskId": "<board-task-id>",
  "status": "success",
  "boardId": "<editable-board-id>",
  "boardTaskIds": ["<board-task-id>"],
  "creditsCost": 17.27,
  "errorCode": null,
  "errorMsg": null,
  "result": {
    "originVideo": {
      "type": "video",
      "format": "mp4",
      "url": "<signed-video-url>",
      "coverUrl": "<signed-cover-url>",
      "resourceId": "<resource-id>",
      "width": 720,
      "height": 1280,
      "duration": 10,
      "durationMs": 10000
    }
  }
}

In the full response, the final video URL is at result.result.originVideo.url. Media URLs are signed; use the returned URL rather than constructing a storage URL. Output dimensions and duration depend on the generated result. Example values are not a price or duration guarantee.

Billing, errors, and retries

• Video Recast follows Board payer, permission, subscription, and credit rules. Charges are settled using actual output duration. The API does not add a second charge.
• Unlimited mode and free-generation guarantees are not supported by this endpoint.
• creditsCost preserves the fractional precision returned by the billing service, without integer truncation or additional rounding. Use a decimal-capable numeric type in your client. During processing, costs may be provisional; use the completed task together with account credit logs for reconciliation.
• Invalid modes, duration, resolution, duplicate reference IDs, wrong file types, or a non-Recast task ID are rejected. Board permissions and uploaded-file validity are checked. See Response Code for the shared error envelope.
• Submission is not idempotent and has no automatic retry guarantee. If a submission times out, do not blindly resubmit: it may create another task and charge. Check the Board for the existing task first.
• A failed submission can leave a created task card on the Board.