Tutorial
How to Call the seedance-2.5 Image-to-Video API: Working curl and Python Examples
On this page
What the seedance-2.5 image-to-video endpoint gives you
seedance-2.5 image-to-video is an asynchronous model endpoint on HiAPI that turns one or two still images into a short video clip. You send it an image (or a pair of images that bookend the motion), describe what should happen, and the platform returns a task that resolves to a video file URL when generation finishes.
In a typical video generation stack, this endpoint sits in the "animate a still" layer. You already have a source image — a product shot, a character render, a storyboard frame — and you want motion rather than a new image. Because the call is asynchronous, your job is to submit the task, keep the task identifier, and poll until the result is ready. That submit-then-poll pattern is shared across HiAPI's long-running generation endpoints, so the client you write here transfers to other models.
The endpoint also exposes native audio options, which matters if your pipeline needs a clip with sound rather than a silent asset you score later. If you need frame-accurate camera moves or loopable motion, image-to-video with explicit first and last frames is often the most controllable option you have without building a 3D scene.
Prerequisites and authentication
Before your first call, gather three things.
1. A HiAPI API key
Every request authenticates with your key, sent as a bearer token in the Authorization header. Keep it out of source control — read it from an environment variable so the same script works locally and in CI.
export HIAPI_API_KEY="your_key_here"
2. A source image the API can fetch
The image inputs are URLs. Host your image somewhere the service can reach — an object store with a signed URL, a CDN, or any public HTTPS location. If you prefer not to expose images publicly, generate a short-lived signed URL rather than making the bucket public.
For first/last-frame workflows you need either one image (first frame only) or two images (first and last frame).
3. An HTTP client
Anything that can send JSON works: curl for a quick smoke test, requests or httpx in Python, fetch in Node. You do not need a special SDK.
The exact base URL, path, and field names for the model live on the model page in the HiAPI console; use those values verbatim in the examples below. Once you have the key and an image URL, you are ready to submit.
First-frame vs last-frame inputs
The two image inputs control different ends of the clip, and choosing between them changes how much control you have over motion.
First frame only. You supply one image and the model generates forward from it. This is the right choice when you want the model to invent the motion: a portrait that slowly turns, a product that rotates, a landscape where clouds drift. You give up determinism about where the clip ends, but you gain creative range and need only one asset.
First and last frame. You supply two images and the model generates a path between them. This is the right choice when the endpoint matters: a logo that assembles into its final lockup, a character that moves from pose A to pose B, an object that slides from left to right across the frame. Supplying a last frame constrains the motion, which usually means fewer surprises and better loopability if you plan to repeat the clip.
A practical rule: if you can describe the clip as "something happens to this image," use a first frame alone. If you can describe it as "this image becomes that image," supply both. When you supply both, keep the two images consistent in framing, aspect ratio, and lighting — mismatched pairs force the model to resolve a jump that reads as a glitch.
Your prompt should complement the frames rather than fight them. Describe the motion, not the still content the model can already see.
Submit your first request with curl
The request below submits an image-to-video task. Replace the endpoint path, model identifier, and field names with the values shown on the seedance-2.5 image-to-video model page in the HiAPI console, and swap in your own image URLs.
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "The camera slowly pushes in as the subject turns toward the light",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
A few things to notice about the shape:
promptdescribes the motion. Keep it short and specific; long lists of adjectives tend to dilute the instruction.first_frame_imageis required for image-to-video.last_frame_imageis optional — drop the field entirely for first-frame-only generation.- Audio options, if you want them, are additional fields in the same JSON body (covered below).
The response is a task object containing an identifier and a status. Save the identifier; you need it for every poll. If the call returns an authentication or validation error instead, check the header and the image URLs before retrying.
The same request in Python
Here is the equivalent submission in Python, factored so the task identifier is easy to capture.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)
Two habits worth adopting early. First, set an explicit timeout on the submission call — a hung request should fail fast, not stall your worker. Second, keep the raw response around during development. The field that holds the task identifier may differ from task_id depending on the endpoint version, and printing the raw JSON once saves you a debugging round.
Polling the async task until the video is ready
Image-to-video generation takes longer than an HTTP request should stay open, so the platform uses the submit-then-poll lifecycle. Submission returns a task identifier; you then query the task endpoint periodically until its status reaches a terminal state.
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")
Structure your polling around four rules:
- Poll a modest interval. Five seconds is a reasonable default. Hammering the endpoint does not make the video render faster.
- Always set a deadline. Tasks can fail or queue longer than expected; an unbounded loop turns a transient issue into a stuck worker.
- Treat
failedandcancelledas terminal. Surface the error field rather than retrying the same task forever. - Use backoff for sustained polling. If you poll many tasks concurrently, grow the interval gradually to avoid bursts.
For production, poll from a background worker or queue rather than inside a web request handler. The result is a video URL; download and copy it into your own storage promptly, since generated asset URLs are typically not permanent.
Handling native audio flags
seedance-2.5 can produce clips with native audio, and the control is a request field alongside your image inputs and prompt — not a separate endpoint. The exact field name and accepted values are listed on the model page; the Python helper above passes an audio boolean by way of illustration.
Whether to enable it depends on what consumes the clip.
Request audio when the output goes straight to an audience — social posts, previews, demos — and you want the clip to feel finished without a second editing pass. Native audio also helps reviewers judge pacing, because sound makes motion timing easier to read.
Skip audio when your pipeline overlays its own soundtrack, when the clip feeds a compositing or editing tool, or when you plan to generate many variants and only score the survivors. Silent generation keeps the asset neutral and avoids syncing problems later.
One practical note on downscaling scope: treat audio as a per-request decision rather than a global setting. A single helper that accepts an audio flag, as above, lets the same code path serve both silent background batches and polished final renders.
If the flag is present but the result is silent, confirm the value serialized as intended — a string "true" versus a boolean true is a common mismatch — before assuming the model ignored it.
Common failure points and next steps
Most first-integration problems fall into four buckets.
Inputs the service cannot fetch
A URL that works in your browser may fail server-side: private buckets, expiring links, or hosts that block non-browser user agents. Use signed URLs with enough lifetime to cover the whole generation, and confirm the image loads from a machine outside your network.
Mismatched frames
When first and last frames differ in aspect ratio, crop, or color temperature, the model has to reconcile a jump. Pre-process the pair to the same dimensions and similar grading before submitting.
Wrong field names or model identifier
The examples here use the request shape from the model page; copy the field names and model string verbatim from the console rather than from memory or older snippets. A typo in a field name is often silently ignored rather than rejected.
Polling that never terminates
If your loop times out repeatedly, log every status value you observe. Seeing an unexpected status string usually explains the stall — your terminal-state check may simply not match what the API returns.
Once a single clip works end to end, the natural next steps are batching multiple images through the same submit-and-poll helper, adding retry with backoff around submission, and writing results to durable storage. You can find the endpoint details, request fields, and parameter reference on the seedance-2.5 image-to-video model page, and adapt the code above to your own images from there.
Related articles
View all articles →-
Tutorial
gpt-6.2-sol in Practice: 5 High-Value Uses of a Text Model in Business
-
Tutorial
gpt-6.2-astra Practical Guide: Integration and Implementation Key Points for 5 High-Value Text Scenarios
A Developer's Checklist from Scenario Selection to Engineering Implementation
-
Tutorial
Tripo H3.1 Practical Application Scenarios: 5 High-Value Use Cases and Implementation Essentials
From text-to-3D to multiview reconstruction: choosing the right mode and parameters by business scenario