Tutorial
seedance-2.5-flash Image-to-Video API Tutorial: curl and Python Requests
A practical integration walkthrough for developers: request shape, first/last frame inputs, async polling, and error triage
On this page
What an image-to-video call actually does
Before you write a single line of code, it helps to know what the API is doing on the other side. A seedance-2.5-flash/image-to-video call is not a synchronous request that blocks until a video file comes back. It is a two-phase, asynchronous workflow: you submit a job, then you poll for its result.
The submit phase
You send a POST with your input image(s) and generation settings. The API validates the payload, enqueues the job, and immediately returns a response containing a job identifier and an initial status. This is fast — typically a moment — because no pixels have been rendered yet. Your job is to capture that identifier and keep it safe.
The render phase
Generation happens in the background. Depending on clip length and settings, this can take a meaningful amount of wall-clock time. During this window you should not expect the final video URL to be available. Instead, you query the job's status.
The result phase
Eventually the job reaches a terminal state: success with a video artifact you can download, or failure with an error you can triage. Once terminal, polling should stop.
Why this matters for your code
Because the model is async, the most common integration mistakes are architectural, not syntactic: assuming the first response contains a video, sleeping in fixed increments instead of polling a status field, and failing to distinguish a transient processing state from a permanent failure. Everything in this tutorial builds toward a clean submit → poll → exit loop, so keep those three phases in mind as we go.
Prerequisites and request anatomy
What you need before the first call
- An API credential. Your HiAPI API key, sent on every request. Keep it in an environment variable (
HIAPI_API_KEY) rather than in source control — the examples below read it that way. - The model identifier. For this tutorial the string is fixed:
seedance-2.5-flash/image-to-video. Treat it as an opaque constant; do not construct it from parts. - A source image. A public URL or a supported inline image reference. The model needs at least a first-frame image.
- An HTTP client.
curlfor smoke tests,requestsfor anything you intend to keep.
The logical fields of a request body
Regardless of language, an image-to-video request body is composed of a few conceptual groups. Knowing them separately makes the JSON easier to reason about:
Model and input
- The model identifier.
- An input object holding the first-frame image and, optionally, a last-frame image. Chapter 4 covers how these interact.
Output settings
- Resolution and duration-related switches.
- The native-audio toggle, which decides whether the generated clip carries an accompanying audio track. Chapter 5 walks through when to flip it.
What comes back
A successful submission returns a job object. The fields you actually need are the job identifier and the current status. Everything else is metadata you can log or ignore. Do not parse the whole response into a typed model on day one — log it, inspect it, then narrow.
A quick reality check before moving on: if your request body contains any field whose name you cannot explain in one sentence, remove it and start minimal. The model page for seedance-2.5-flash/image-to-video is the reference for the exact accepted field names.
Submitting a job with curl
Start with the smallest request that can possibly work, then add fields one at a time. Here is a minimal submission with curl:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
Annotating each field
Authorization— your API key as a bearer token. If this is wrong you get an auth error before any validation runs, so check it first when debugging.Content-Type: application/json— required; omitting it produces confusing downstream errors.model— the fixed model identifier. A typo here is a 4xx, not a silent fallback.input.first_frame_image— the opening image of the clip. Use a URL your network can actually reach; private or expired URLs fail at fetch time, not at submit time.
Reading the response
The response is JSON containing the job identifier and status. Save the identifier immediately — this is what you will poll in chapter 7. A quick way to extract it in the shell:
# after the curl above, piped through jq
# {"job_id": "...", "status": "queued"}
Adding a last frame
To control the ending frame as well, add a second image inside the same input object. The field name and accepted format are the ones the model documents — do not guess an alternate spelling; the API rejects unknown keys rather than ignoring them.
Once the minimal request works, you have a smoke test you can re-run whenever something breaks. Keep it in a file; it is worth more than any amount of prose when a service is misbehaving at 2 a.m.
First-frame and last-frame inputs
The input images are the single largest determinant of whether a job succeeds. They shape the clip's content, and they are also the most common source of rejected requests.
What the first frame controls
The first-frame image sets the opening state of the generated clip: composition, subject, lighting, and color. The model generates motion and continuation from that starting point, so the image should look like a frame you would actually want at time zero. A blurry, cropped, or heavily compressed source image does not magically improve downstream.
What the last frame controls
Providing a last-frame image pins the ending state. This is useful when the clip has to land on a specific shot — a product beauty frame, a logo reveal, a matching cut in an edit. When omitted, the model chooses its own ending, which is fine for exploratory work but unpredictable for production.
How the two interact
When both are supplied, the model interpolates between them. That has practical consequences:
- Continuity beats contrast. Two frames from the same scene with modest motion between them produce a far more coherent clip than two unrelated images. If the frames are wildly different, expect a visible morph rather than a plausible transition.
- Aspect ratio should match. Mismatched aspect ratios between first and last frame force the model into awkward reframing. Crop both to the same ratio before submitting.
- Resolution should be comparable. Sending a sharp first frame and a low-resolution last frame gives the model conflicting signals.
A pre-submit checklist
Before you send, verify: both image URLs are publicly reachable and not expiring mid-job; both are in a supported format; both share an aspect ratio; neither is a screenshot with UI chrome you do not want rendered. A quick HEAD request against each URL catches most of these cheaper than a failed generation job does.
If you do hit a rejection, the error message will usually point at the input object. Validate the images locally first — dimensions, format, and reachability — and only then suspect the API.
Resolution and native audio settings
Output settings are where developers tend to over-configure. The good news is that the defaults are sane; the risk is in cargo-culting values from another model's documentation.
Resolution
Resolution determines the size of the delivered video and, by extension, generation time and output weight. Two rules of thumb:
- Choose for the destination, not for the number. A clip destined for a mobile feed does not need to be rendered at a large size only to be downscaled. Pick the smallest resolution that satisfies your target surface.
- Prefer one of the documented presets. Passing arbitrary or unsupported values is a common cause of rejected requests. If you need a specific frame, crop or scale after generation rather than fighting the request validator.
Native audio
The native-audio toggle decides whether the generated clip includes an accompanying audio track produced along with the video. Consider whether you want it:
- Enable it when the clip is a finished deliverable that will be viewed with sound — social content, short promos, character scenes where ambient audio sells the motion.
- Disable it when you will lay your own music or voiceover in an editor, or when the clip is an intermediate asset. Generating audio you will discard is wasted work and makes downstream processing heavier.
Duration
Duration is coupled to everything else: longer clips take longer to generate and are more prone to drift in subject consistency. For a first integration, start short. Confirm the pipeline works end to end with a brief clip, then lengthen once you trust the plumbing.
Keep the settings object small
If you find yourself adding settings to fix a quality problem, stop and check whether the problem is actually in the input images. Most disappointing outputs trace back to chapter 4, not to a missing knob. Configure deliberately, log the exact settings object alongside each job identifier, and you will be able to attribute quality changes to a specific tweak.
Doing the same request in Python
The curl request translates directly into Python. The goal here is not a framework — it is a small, readable client that submits a job and returns the identifier, so the polling layer can stay separate.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Why it is structured this way
- Environment variables for config. The base URL and key live outside the code so the same client runs against different environments.
timeout=30on the submit. Submission is fast; a submit that hangs indicates a network or auth problem, and you want to find out early rather than block a worker indefinitely.raise_for_status()before parsing. A 4xx body is usually a JSON error object, not a job. Raising first keeps the happy path clean and lets the caller handle failures explicitly.- Separate submit from poll.
submit_jobdoes exactly one thing. The polling loop in the next chapter takes the returned dict and owns the waiting.
Porting it into a service
In a real service, wrap the call so failures surface as a typed exception carrying the status code and response body — you will want the raw body when debugging in production. Log the payload alongside the returned job identifier; when a colleague asks why one particular clip looks wrong, that log line is the entire investigation.
The field names are identical to the curl example. If you can read one, you can read the other — which is exactly why starting with curl is worth the five minutes.
Polling for the result without hammering the API
Now the job exists and has an identifier. The naive approach — sleep for sixty seconds and hope — fails two ways: it wastes time when the job finishes early, and it fails entirely when the job takes longer.
Poll the status field, not the clock
Write a loop that queries the job's current status and branches on it:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # bounded exponential backoff
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
The properties that matter
- Explicit terminal states. Only
succeededandfailedend the loop. Any other status is transient. Do not treat unknown statuses as failures — new intermediate states appear over time, and your loop should tolerate them. - Bounded backoff. Start small (a couple of seconds) and grow by a modest factor, capped around ten to fifteen seconds. This keeps short jobs snappy without hammering the endpoint during long renders.
- A hard deadline. Always cap total wait time. Without it, a stuck job pins a worker forever. Choose the cap from your longest realistic render plus margin.
- Separate failure from timeout. A
failedjob is a generation error worth reporting to the user. A timeout is an infrastructure condition worth retrying or investigating separately. Conflating them makes incident review miserable.
In a web service
Do not run this loop inside the request handler that the user is waiting on. Submit, store the job identifier, return immediately, and let a background worker poll and deliver the result — via a webhook, a queue, or a row update the frontend watches. The loop above is a worker concern, not an HTTP concern.
Troubleshooting common failures
Most failures fall into three classes. Identify the class first, then the specific cause.
Class 1: Input validation failures
Symptom: an immediate 4xx at submit time, before any rendering.
Diagnose in this order:
- Is the image URL reachable? Fetch it yourself from the same network. Expired signed URLs and private buckets are the top cause.
- Is the format supported? Re-encode to a standard format rather than debating.
- Do first and last frames agree? Mismatched aspect ratios or wildly different scenes often surface as validation or quality problems.
- Did you add a field with the wrong name? Unknown keys are usually rejected rather than ignored. Compare against the model reference.
Class 2: Parameter mismatches
Symptom: rejected request citing a setting, or an output that ignores your configuration.
- Unsupported resolution or duration. Use documented values only; arbitrary numbers are a common rejection.
- Model identifier typo. It is a fixed string — copy it, do not retype it.
- Wrong nesting. Settings inside
inputthat belong at the top level, or vice versa, produce confusing errors. Keep the request shape from chapter 3 as your reference.
Class 3: Polling timeouts and job failures
Symptom: the job was accepted but never reaches a terminal success state.
- Confirm you are polling the right identifier. Copy-paste errors across jobs are surprisingly common in batch scripts.
- Check whether the status is genuinely progressing. Log each poll's status so you can see whether a job is moving or frozen.
- Distinguish API failure from generation failure. If the poll request itself errors, it is transport. If the job reports
failed, read the error body — it usually names the input that caused it. - Re-run the minimal
curlsmoke test. If the smoke test fails too, the problem is credentials or the service; if it succeeds, the problem is in your payload.
A general debugging posture
Log three things on every job: the exact request payload, the returned job identifier, and the final status with error body. With those three, almost every incident is a five-minute diagnosis rather than an afternoon. When in doubt, strip the request back to the minimal form from chapter 3 and add fields until it breaks — the last added field is your culprit.
Related articles
View all articles →-
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
-
Tutorial
gemini-4-neon Real-World Use Cases in Practice: 5 High-Value Applications and Integration Essentials
-
Tutorial
How to Call seedance-2.5-flash Text-to-Video via the HiAPI API (curl & Python)
A working request walkthrough for developers: endpoint, parameters, async task handling, and runnable curl and Python examples
10 min read