Tutorial
How to Call seedance-2.5-flash Reference-to-Video via the HiAPI API (curl + Python)
A working request, a runnable Python script, and how to handle async job polling
On this page
What reference-to-video means in practice
Reference-to-video is a generation pattern where you give the model two things at once: a written prompt describing the motion and scene, plus one or more reference assets that anchor what should appear on screen. The prompt carries intent ("slow push-in, character turns and smiles"), and the references carry identity and look (a character, a product, a visual style).
The model endpoint for this workflow is seedance-2.5-flash/reference-to-video, served through the HiAPI unified API. You send model, prompt, and reference assets together in a single request body. There is no separate upload step you have to orchestrate, and no per-asset registry to maintain.
The practical consequence: this is a long-running operation. A short video still takes far longer to render than a text completion, so the API treats the call as an async job. Your request creates the job; a second call retrieves its result. That submit-then-poll shape is the single most important thing to design for, and it is what the rest of this tutorial builds toward.
Everything below stays inside the HiAPI interface: one base URL, one auth header, one endpoint family.
Before you send your first request
Three things need to be in place before your first call.
1. An API key
Create a key in the HiAPI console and keep it out of source control. The examples below read it from an environment variable:
export HIAPI_API_KEY="your_key_here"
If you are unsure of the current key format or header convention, check the platform's API documentation in the console — do not guess, and do not hardcode a key into a script you might share.
2. The base URL and auth header
All calls go to the HiAPI base URL with your key in the Authorization header. Set it once as a variable so every request is consistent:
export HIAPI_BASE_URL="https://api.hiapi.ai"
Use the base URL exactly as documented for your account — a trailing slash mismatch is a common cause of confusing 404s.
3. The model endpoint
Your target is seedance-2.5-flash/reference-to-video. Refer to it by this identifier in the request body rather than embedding it in the path, so switching models later is a one-line change.
You also need your reference assets reachable as URLs (or whatever asset form the endpoint documentation specifies). Have them hosted and publicly accessible before you start — a broken reference URL is the most frequent cause of a job that submits fine and then fails during generation.
Once these three are set, you are ready to build a body.
Build the request body with reference assets
The request body has three conceptual parts: which model, what you want, and what to reference.
Model
Set model to seedance-2.5-flash/reference-to-video. Treat it as a plain string field — no URL encoding, no path segments.
Prompt
Write the prompt as a shot description, not a wish list. State the subject, the action, the camera behavior, and the pacing. "A person in a red jacket walks toward the camera, medium shot, slow dolly-in, soft daylight" gives the model far more to work with than "nice video of a person." Keep the prompt consistent with the references you supply: if two references show different characters, say which one leads.
Reference assets
References are where this endpoint differs from a plain text-to-video call. You pass one or more assets that define what should stay consistent across frames. Practical rules that save iterations:
- Use the minimum number of references that pins down identity. One strong reference usually beats four mediocre ones.
- Keep references consistent with each other. Conflicting angles or styles make the output drift.
- Prefer clean, well-lit sources. Cropped, blurry, or heavily filtered references propagate those flaws.
- Verify each URL resolves before submitting — fetch it yourself first.
Exactly how reference assets are keyed in the body (array field name, object shape, supported asset types) should come from the endpoint's request schema in the HiAPI docs. Build the body from that schema rather than from memory; the schema is the source of truth for field names, and a mismatched key is a silent failure.
Validate your JSON locally (python -m json.tool body.json) before it ever reaches the network. A malformed body is the cheapest error to catch and the most annoying to debug from a stack trace.
A working curl request
The command below follows the submit-then-poll pattern: it creates a job and prints the JSON response, which contains the job identifier you will poll with.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "A person in a red jacket walks toward the camera, medium shot, slow dolly-in, soft daylight",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Replace the reference URLs with your own hosted assets, and confirm the endpoint path and field names against the model page in the HiAPI docs before relying on this in production — schema details are authoritative, this snippet is illustrative.
What to look for in the response:
- An id (or task/job identifier) — capture it; every poll needs it.
- A status field indicating the job was accepted.
- Any warnings about assets that were ignored or rejected.
Pretty-print it for readability:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Keeping the body in body.json is worth the small extra step: it version-controls cleanly, diffs readably, and removes shell-quoting bugs from the debugging surface.
The same call in Python
Here is the equivalent call in Python, written to be runnable as-is once your environment variables are set. It uses only the standard library so there is nothing to install.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="A person in a red jacket walks toward the camera, medium shot, slow dolly-in, soft daylight",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Two details matter more than they look. First, the timeout=60 — the submit call should return quickly, but a hung connection is worse than a fast failure. Second, result.get("id") handles the case where the response shape surprises you instead of raising KeyError inside your happy path.
If you prefer requests or httpx, the translation is direct: same URL, same headers, same JSON body. The body construction is the part worth copying; the HTTP client is swappable.
Polling the async job until it finishes
Video generation is not a request you wait on. You submit, get an identifier back, and then check status periodically until the job reaches a terminal state. Two properties make this safe: polling is cheap, and the submit call has already done the expensive work.
The loop
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
A tighter loop is not faster; it just burns rate limit. A five-second interval is a reasonable default for video jobs.
Design notes
- Always have a deadline. A job that never terminates must not hang a request thread forever.
- Treat unknown statuses as "keep waiting", not as success. Only explicit success is success.
- Do not poll inside a web request handler. Submit in the handler, return the job id to the client, and let a background worker poll and persist the result.
- Persist the job id and status transitions so an interrupted process can resume rather than resubmit and pay for the render twice.
This submit-then-poll split is what lets a slow video pipeline sit behind a fast API.
Common errors and how to fix them
Almost every failure in the first hour falls into one of four buckets. Check them in this order.
1. Authentication
Symptoms: an unauthorized or forbidden response before any job is created.
Checks: is HIAPI_API_KEY actually populated in the shell or process that runs the script? Is the header exactly Authorization: Bearer <key>? Are you loading the key at import time while your script expects it later? Print the first few characters of the resolved key (never the whole thing) and confirm it is not an empty string.
2. Endpoint path
Symptoms: not found, usually instantly.
Checks: base URL plus path with exactly one slash between them — this is why the Python example calls .rstrip("/"). Confirm the generation path and the polling path against the model page in the docs; a polling URL missing the job id segment will 404 every time. A trailing slash that the server does not expect produces the same symptom.
3. Malformed request body
Symptoms: a validation error, or a job that is accepted and fails immediately.
Checks: run json.dumps(body) and inspect it. Does model match seedance-2.5-flash/reference-to-video exactly? Is the reference field an array, and is each entry a string URL that resolves in a browser? Are you sending Content-Type: application/json? Send the body through python -m json.tool to rule out syntax errors before they reach the network.
4. Job status
Symptoms: the submit call worked, but the job fails or never completes.
Checks: read the error field in the status response — it usually names the cause, most often an unreachable or unsupported reference asset. If the job just sits there, confirm you are polling the right id and that your loop's status comparison covers the terminal statuses the API actually returns. Log every status transition; the last one before the failure is your diagnostic.
One rule that shortens all four: log the request id and job id for every call. When something breaks, an id turns a vague bug report into a specific lookup.
Where to go next
You now have the full shape: build a body with a prompt and reference assets, submit it, poll until terminal, and handle the four common failure classes. From here, the natural next steps are engineering ones rather than API ones.
- Wrap submission in a retry with backoff for transient network errors, but never retry a job that already has an id — that is a duplicate render.
- Move polling into a worker or queue so your HTTP layer stays responsive and jobs survive process restarts.
- Store the job id alongside your own request metadata (prompt, references, requesting user) so results are traceable months later.
- Gate reference assets behind validation — fetch each URL when the user supplies it, before you spend a job on it.
For the authoritative request schema, supported asset forms, and current endpoint details, see the seedance-2.5-flash reference-to-video model page on HiAPI. Build against that schema, keep the submit-then-poll split, and the integration stays boring — which is exactly what you want from a video pipeline.
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