Seedance 2.5 Image to Video API

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

Image, video, and audio models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model	seedance-2.5/image-to-video
Capability	First-frame / first-last-frame image-to-video
Resolution	480p / 720p
Duration	4-30 seconds

Generate up to 30 seconds from a first frame or a first/last-frame pair, with the output ratio following the first frame and optional synchronized audio.

Production guidance

Calling the API

Use first_frame_url together with last_frame_url.
Before task creation and quota pre-consumption, HiAPI checks HTTP(S) URL / data URL images and snapshots the exact content only after the entire batch passes. Detected format, size, dimension, or aspect-ratio violations return HTTP 400 / INVALID_REQUEST; no task is created and no quota is charged. Only first_frame_url accepts asset://<id>; its content remains provider-validated.
Unavailable snapshot storage or preflight capacity returns HTTP 503 / STORAGE_UNAVAILABLE; concurrent or daily preflight limits return HTTP 429. These failures likewise create and charge no task.
Use callback.url for terminal notifications and GET /v1/tasks/:id as a fallback query.
Artifact URLs expire; copy files you need to keep into persistent storage.

Best suited for

Animate a still

Add natural motion and camera movement to a poster, product image, illustration, or scene.

first_frame_url

Controlled transitions

Specify both endpoints to create a coherent transition between two images.

first_frame_urllast_frame_url

Audio clips from images

Generate synchronized dialogue, effects, and background music for an image-driven shot.

generate_audio

Request parameters

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

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Slow push-in as petals move gently in the wind",
    "first_frame_url": "https://example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": true
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Slow push-in as petals move gently in the wind",
    "first_frame_url": "https://example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": true
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Slow push-in as petals move gently in the wind",
    "first_frame_url": "https://example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": true
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Model ID.

example seedance-2.5/image-to-video

input object required

First-frame and first/last-frame image-to-video parameters.

prompt string required

Motion, camera, scene, and audio instructions. Eleven prompt languages are supported.

first_frame_url string optional

First-frame HTTP(S) URL, data URL, or asset://<id> asset ID. HiAPI preflight supports jpeg, png, webp, bmp, tiff, and gif; under 30 MB; each side 300-6000 px; aspect ratio 0.4-2.5. SVG, HEIC, and HEIF are not supported.

last_frame_url string optional

Last-frame image URL used with first_frame_url. It must meet the same format, 30 MB, 300-6000 px, and 0.4-2.5 aspect-ratio limits. If its ratio differs from the first frame, it is center-cropped.

reference_image_urls string[] optional

Array of up to 30 reference image URLs for subject, style, or composition guidance. Each image must be under 30 MB, have sides from 300 to 6000 px, and an aspect ratio from 0.4 to 2.5. SVG is not supported.

reference_audio_urls string[] optional

Array of up to 10 reference audio clips. Supports wav and mp3; each clip is 2-30 seconds and under 15 MB; combined duration is limited to 30 seconds.

resolution enum optional

Output video resolution. Defaults to 480p.

default 480p enum: 480p720p

duration integer optional

Output duration in seconds. Accepts integers from 4 to 30 and defaults to 5 seconds.

default 5

aspect_ratio enum optional

Output aspect ratio, derived from the first frame.

default adaptive enum: adaptive

generate_audio boolean optional

Generate synchronized dialogue, effects, and background audio.

default true

output_format enum optional

Output format. mp4 has broad compatibility; mov is intended for professional post-production.

default mp4 enum: mp4mov

watermark boolean optional

Add an AI-generated watermark to the bottom-right corner.

default false

web_search boolean optional

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

default false

callback object optional

Sends the task object when the task reaches a terminal state; the polling endpoint wraps the same object in data.

url string required

HTTPS URL that receives terminal notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Triggers when the task reaches a terminal state.

default final enum: final

Every fetchable image in first_frame_url, last_frame_url, and reference_image_urls must be jpeg, png, webp, bmp, tiff, or gif; under 30 MB; 300-6000 px on each side; and have an aspect ratio from 0.4 to 2.5. SVG, HEIC, and HEIF are not supported. Fetchable images are capped at 120 MB combined and reference images at 30 items; GIF input is snapshotted as its first frame in PNG.
input.aspect_ratio controls the output video ratio and does not relax the 0.4-2.5 input-image limit. An overly wide or tall image is rejected before task creation even when adaptive is used.
Preflight guarantees only the deterministic constraints documented here; asset://<id> IDs and other provider-specific file validity remain provider-authoritative.
Use seedance-2.5/reference-to-video for reference videos. This model supports first/last frames, reference images, and reference audio.

Example requests

First-frame generation

Pass only the first frame and let the model create motion.

Request body

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Move from a static view into a slow orbit",
    "first_frame_url": "https://example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive"
  }
}

First/last-frame transition

Generate a coherent transition between two images.

Request body

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "A natural time-lapse transition from day to night",
    "first_frame_url": "https://example.com/day.jpg",
    "last_frame_url": "https://example.com/night.jpg",
    "resolution": "480p",
    "duration": 8,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

Getting the result

Read data.taskId from the create-task response.
Wait for the callback or query GET /v1/tasks/:id; polling puts the task under data.
When status=success, read the video URL from output type=video; a callback reads output directly.

FAQ

How do callback and polling responses differ?

They contain the same task fields but use different HTTP envelopes: polling puts the task under data, while the callback body is the task object itself.

Can I pass only first_frame_url?

Yes. last_frame_url is optional; without it, the model creates the rest of the shot from the first frame.

Why is an image rejected when aspect_ratio is adaptive?

aspect_ratio controls the output video. The error checks the input image itself; every first frame, last frame, and reference image must have a pixel aspect ratio from 0.4 to 2.5.

When should I use the reference-to-video model?

Use seedance-2.5/reference-to-video when a video should guide motion or camera movement. This model supports first/last frames, reference images, and reference audio.