Seedance 2.5

seedance-2.5/reference-to-video

seedance-2.5/image-to-video seedance-2.5/reference-to-video

Pricing

seedance-2.5/reference-to-video per second

Specifications	Unit Price
480P	$0.1215
720P	$0.2715
1080P	$0.680

Introduction coming soon

A detailed guide for this model is being prepared. Pricing, parameters and the API docs below are already available.

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: seedance-2.5/reference-to-video

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for seedance-2.5/reference-to-video and route default — see the parameter table below.

promptstringRequired

Instructions for using the reference media. Address items in order as @image1, @video1, or @audio1. This model ID is for reference-guided generation, not video editing or extension.

durationintegerOptionalDefault: 5

Output duration in seconds. Use -1 for automatic duration, or an integer from 4 to 30.

Options:-145678910

Show all (20)

1112131415161718192021222324252627282930

resolutionstringOptionalDefault: "480p"

Output resolution. Seedance 2.5 supports 480p, 720p, and 1080p.

Options:480p720p1080p

web_searchbooleanOptionalDefault: false

Allow the model to search the web for current information mentioned in the prompt.

aspect_ratiostringOptionalDefault: "adaptive"

Output aspect ratio. adaptive lets the model follow the reference material.

Options:16:94:31:13:49:1621:9adaptive

output_formatstringOptionalDefault: "mp4"

mp4 is the compatible default; mov targets professional post-production.

Options:mp4mov

generate_audiobooleanOptionalDefault: true

Generate synchronized dialogue, effects and background audio.

reference_audio_urlsarrayOptionalmaxItems 10

Up to 10 reference audio clips. Each must be wav or mp3, under 15 MB, and 2-30 seconds. Combined audio duration must not exceed 30 seconds. Provide audio references together with at least one reference video.

Array [ string ]

reference_image_urlsarrayOptionalmaxItems 30

Up to 30 reference images. Supported formats: jpeg, png, webp, bmp, tiff, and gif; under 30 MB each; 300-6000 px per side; aspect ratio 0.4-2.5. SVG, HEIC, and HEIF are not supported.

Array [ string ]

reference_video_urlsarrayRequiredminItems 1maxItems 10

Up to 10 reference videos. Each must be mp4 or mov, 480p or 720p, 24-60 fps, under 200 MB, 2-30 seconds, 300-6000 px per side, and aspect ratio 0.4-2.5. Combined video duration must not exceed 30 seconds.

Array [ string ]

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "resolution": "480p",
    "web_search": false,
    "aspect_ratio": "adaptive",
    "output_format": "mp4",
    "generate_audio": true,
    "reference_video_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5/reference-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "resolution": "480p",
      "web_search": false,
      "aspect_ratio": "adaptive",
      "output_format": "mp4",
      "generate_audio": true,
      "reference_video_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "seedance-2.5/reference-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "resolution": "480p",
          "web_search": false,
          "aspect_ratio": "adaptive",
          "output_format": "mp4",
          "generate_audio": true,
          "reference_video_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}