Blog

Tutorial

How to Call the seedance-2.5 Image-to-Video API: Working curl and Python Examples

Nov 12, 2026 10 min read
Abstract cover art: overlapping translucent glass panes casting cool blue bands across a pale gray field, flat and architectural.
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:

  • prompt describes the motion. Keep it short and specific; long lists of adjectives tend to dilute the instruction.
  • first_frame_image is required for image-to-video. last_frame_image is 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 failed and cancelled as 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 →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs