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
On this page
What seedance-2.5-flash/text-to-video Gives You
seedance-2.5-flash/text-to-video is a text-to-video generation endpoint on the HiAPI API. You send a text prompt describing the scene you want, and the model returns a generated video. That is the whole contract: text in, video out.
Because video generation takes longer than a typical chat completion, this endpoint is asynchronous. A single call does not block until the video is ready. Instead, the request creates a generation task, and you retrieve the result once the task reaches a terminal state. If you have integrated any long-running media API before, the shape will feel familiar: submit, store the task identifier, then fetch the result.
The integration work on your side is therefore three things: constructing a valid submission request, persisting the task ID, and reliably fetching the finished video. This tutorial walks through all three with runnable curl and Python code, then covers parameter validation, polling versus callbacks, and the failure modes that trip up most first integrations.
This guide fits you if you are building a pipeline that turns prompts into short video clips programmatically — a content tool, a prototyping backend, or an internal generation service. If you need synchronous responses, or you are looking for image generation rather than video, a different endpoint is the better fit. If this matches your use case, continue to the prerequisites.
Prerequisites and Getting Your API Key
Before the first request, confirm three things.
A HiAPI account and API key
All requests to the endpoint are authenticated with an API key tied to your HiAPI account. Create the key in your account dashboard and keep it out of source control. The examples below read it from an environment variable so you can paste them into a terminal or a script without editing inline secrets:
export HIAPI_API_KEY="your_api_key_here"
A client that can make HTTPS requests
For the curl walkthrough you need curl, which ships with macOS and most Linux distributions. For the Python section you need Python 3 and the requests library (pip install requests). No vendor-specific SDK is required — the endpoint is plain HTTPS with JSON bodies, so any HTTP client works, from fetch in Node to httpx in Python.
A way to store state between requests
Because generation is asynchronous, you need somewhere to keep the task identifier returned by the submission call — a database row, a job queue, a JSON file during testing. If you plan to use callbacks instead of polling, you also need an HTTPS endpoint that HiAPI can reach.
With a key in hand and a capable client, you are ready to submit a request.
Your First Working Request with curl
The submission call is a POST with a JSON body. The exact endpoint path and authentication header name are documented on the model page — use those values verbatim; do not infer them from other APIs. The structure of the call looks like this:
curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
}'
A few notes on the pieces:
- Method and path.
POSTcreates a new generation task. The path identifies the model; confirm it against the model page before copying it into your own configuration. - Headers. The
Authorizationheader carries your key, andContent-Type: application/jsontells the server how to parse the body. - Body. At minimum, send a
promptstring. The prompt is the creative input — everything the model renders comes from it, so make it explicit about subject, motion, lighting, and camera behavior.
If the request is accepted, the response contains a task object. You do not get a video URL immediately. Extract the task identifier from the response and store it. The precise field names are part of the documented response schema on the model page; treat them as the source of truth and do not hardcode guesses into your client until you have seen one real response.
You can inspect the raw response with curl first, then move the same call into code once you understand the shape.
Choosing Parameters: Prompt, Resolution, and Duration
Only prompt is strictly required, but a few optional parameters shape the output and the cost of the request. Set them deliberately rather than accepting defaults blindly.
Prompt
The prompt is the highest-leverage parameter. Write it the way you would brief a camera operator: subject, action, environment, lighting, and shot style. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" gives the model far more to work with than "a city". Keep prompts within any documented length limit on the model page.
Resolution
Higher resolution means more detail and larger output files, and it may take longer to generate. Video generation is typically billed by output duration, but confirm the current billing basis and any resolution tiers on the price panel and model documentation rather than assuming. Pick the lowest resolution that meets your delivery target — upscaling later is often cheaper than generating everything at maximum quality.
Duration
Duration controls how many seconds of video the model produces, and it usually drives both latency and cost. Short clips are better for iteration: refine the prompt at a short duration until the motion looks right, then regenerate at the final length.
Validate before sending
Before you wire values into production code, check the model page for the accepted range of each parameter — allowed durations, supported resolutions, and any enum values. Then validate client-side: reject out-of-range durations and unknown resolution values before the request leaves your process. This turns a class of server-side validation errors into immediate, cheap failures in your own logs.
The same rule applies to parameter names. Copy them from the documentation; a typo like a stray underscore in a duration field will typically be rejected or silently ignored, and silent ignores are the harder bug to find.
The Same Request in Python
Here is the equivalent submission in Python. It reads the key from the environment, posts the JSON body, checks the status code, and returns the task identifier from the documented response field.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_video(prompt: str, **options) -> str:
payload = {
"prompt": prompt,
**options, # e.g. resolution="720p", duration=5
}
response = requests.post(
f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
body = response.json()
task_id = body["id"] # confirm the field name on the model page
return task_id
if __name__ == "__main__":
task_id = submit_video(
"A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
)
print("submitted task:", task_id)
A few deliberate choices in this snippet:
- Timeouts. The submission call should return quickly, but an explicit
timeoutprevents a hung socket from stalling your worker. raise_for_status(). Fail on HTTP errors immediately instead of parsing an error body as if it were a success.- Keyword options. Passing
**optionskeeps the call site readable and makes it trivial to addresolutionordurationonce you have confirmed the exact names on the model page. - Returning the ID. The function's job ends at submission. Persist that ID somewhere durable — the next section uses it to fetch the result.
In a real pipeline, treat submit_video as one step in a queue-driven workflow: enqueue it, store the returned task ID with your job record, and let a separate worker handle retrieval.
Handling Async Results: Polling and Callbacks
After submission you have a task ID and no video. There are two ways to close that gap.
Polling
Poll the task status endpoint on an interval until the task reaches a terminal state, then take the output URL from the completed response.
import time
import requests
def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}", # confirm path on the model page
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()
state = task["status"]
if state == "completed":
return task
if state == "failed":
raise RuntimeError(task.get("error", "generation failed"))
time.sleep(delay)
delay = min(delay * 1.5, 15) # gentle backoff, capped
raise TimeoutError(f"task {task_id} did not finish in time")
Three practical rules for polling:
- Back off. Start with a short delay and increase it. Constant tight polling wastes quota and adds load for no benefit.
- Bound it. Every poll loop needs a deadline. Video generation can take a while, but an unbounded loop will eventually hang your worker forever on a stuck task.
- Distinguish states. Handle
failedexplicitly so a bad prompt does not silently look like a timeout.
Callbacks
If you register an HTTPS callback URL, HiAPI can notify you when the task finishes, and you avoid polling entirely. Two rules make callbacks safe:
- Verify before trusting. Treat the callback as unauthenticated input until you have verified its signature or provenance using the mechanism documented for the platform.
- Be idempotent. Callbacks can be delivered more than once. Key your handler on the task ID and make processing repeated deliveries a no-op — store the result once, acknowledge duplicates.
Whichever you choose, retrieval is idempotent: fetching the result URL for a completed task should return the same video, so retries after a network error are safe.
Common Errors and How to Fix Them
Most failures fall into a small set of buckets. Work through this list before assuming undocumented behavior.
Authentication failures
A 401 or 403 almost always means a missing, malformed, or expired key. Check that the Authorization header is present, that the scheme matches the documentation exactly, and that the environment variable actually contains a key — an empty string produces a confusing but auth-related failure.
Validation rejections
A 4xx with a validation message means the server rejected your parameters. Re-read the allowed ranges on the model page and confirm parameter names character by character. If a duration or resolution is out of range, the fix is client-side validation, as described earlier — fail fast in your own code instead of round-tripping to the server.
Tasks stuck in a non-terminal state
If polling never sees completed or failed, the task may still be running, or your poll loop may be querying the wrong task ID. Log the ID you submitted and the ID you polled and compare. Your loop should also enforce a deadline; when it trips, surface the task ID rather than retrying blindly.
Results that do not arrive after a callback
If you rely on callbacks, check that your endpoint is publicly reachable over HTTPS, that it returns a success status quickly instead of doing heavy work inline, and that duplicate deliveries are handled idempotently. A callback handler that errors on the second delivery of the same task will look like a lost result.
Repeated submissions of the same job
If your worker retries the submission call after a timeout, you can create duplicate tasks. Make submission idempotent on your side by recording a client-side request key or job ID in your own database before calling the endpoint, and checking it before retrying.
The general principle: when something fails, read the error body and the model documentation before changing code. If a value or field is not documented, avoid assuming it exists — verify it against the model page and adjust the request accordingly.
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
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
14 min read