Tutorial
Calling muse-video-1.0/text-to-video via the HiAPI API: curl and Python Guide
Request fields, async polling, and a runnable example request
On this page
Before You Send: Auth, Endpoint, and Model Identifier
muse-video-1.0/text-to-video turns a text prompt into a generated video clip. You send a prompt and a handful of controls, the service renders a clip, and you get back a URL or reference you can download.
The important architectural detail is that this call is asynchronous. A video render takes long enough that the API does not hold your HTTP connection open until the file is ready. Instead, the flow has two phases:
- Submit — you POST the prompt and parameters. The response comes back quickly with a job identifier and an initial job state.
- Poll — you GET the job by identifier at intervals until its state becomes terminal (succeeded or failed), then retrieve the result.
This submit-then-poll shape is the single most useful thing to internalize before writing code. It changes how you structure your application: the submitting request is not where the video appears, and any error you encounter belongs to a specific phase — submission, validation, rendering, or retrieval. Keeping those phases distinct in your own code (separate functions, separate logging) makes the rest of this guide much easier to apply.
The model string you pass is exact: muse-video-1.0/text-to-video. The vendor/model form is the convention across HiAPI model endpoints, and it is how the API routing knows which generator to invoke.
Building the Request: Prompt, Duration, and Audio Fields
Three things must be in place before your first request.
API key
Every request is authenticated with a bearer token. Store it in an environment variable rather than in source code, so it never lands in a commit:
export HIAPI_API_KEY="your_key_here"
Send it as an Authorization: Bearer $HIAPI_API_KEY header. If a request fails with an authentication-type error, this header is the first thing to check — wrong variable name, trailing whitespace, or an unset value in the current shell are the usual culprits.
Base URL
All calls share one base URL for the HiAPI platform. Use the current value from your account dashboard or API reference rather than copying it from an old snippet; keep it in a variable so it is changed in exactly one place.
Model identifier
The model string is muse-video-1.0/text-to-video. Treat it as a case-sensitive literal. Do not assemble it from parts or guess variants such as different casing or a missing suffix — an unknown model identifier is a validation error, not a fallback.
With those three elements in hand, you can build the request body.
A Working curl Request
The request body is JSON. Conceptually it contains three groups of fields.
Prompt
The prompt is the creative instruction and carries most of the output quality. A useful prompt describes subject, action, camera behavior, lighting, and style in concrete terms rather than adjectives alone. This is a plain string field.
Duration
Text-to-video models need to know how long the clip should be. Duration is a request field, and it also affects cost: generation is billed by output seconds. Because the acceptable range and default are defined by the model at a given time, read the exact field name and allowed values from the live API reference for muse-video-1.0/text-to-video instead of guessing. Passing an out-of-range duration is a validation failure.
Audio
muse-video-1.0/text-to-video supports audio-related controls alongside the visual generation. These are also request fields — typically toggles or audio-prompt style inputs — and their exact names and accepted values are documented in the same API reference. A conservative approach for a first integration is to omit optional audio fields entirely, confirm a working video comes back, then layer audio options in one at a time.
A minimal body therefore looks like this shape (field names illustrative — confirm against the reference):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "A slow aerial push over a foggy pine forest at sunrise, soft volumetric light, cinematic",
"duration": 5
}
Because the parameter surface can evolve, the reliable habit is: fetch the reference for the model, copy the field names verbatim, and validate locally before sending.
The Same Request in Python
The submit call is a single HTTP POST. The exact resource path is defined by the HiAPI API reference; the example below uses the conventional jobs endpoint with the model in the body.
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "A cardboard robot walks through a rainy neon alley, reflections on wet asphalt, 35mm look",
"duration": 5
}'
The response is small and returns quickly. What matters in it is the job identifier and the state. A typical shape:
{
"id": "job_abc123",
"status": "queued"
}
Record the id — that is your handle for every subsequent call. A status of queued or processing is expected and means the request was accepted, not that anything is wrong.
To poll manually from the shell:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Run this a few times with a pause in between and watch status move toward a terminal value. In practice you want this loop in code, not in your terminal history.
Handling Async Results and Polling Without Hammering the API
The Python version does the same two things — submit, then poll — but adds timeout handling, bounded retries, and result saving so it is safe to run unattended.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"A glass terrarium on a wooden desk, morning light, dust motes drifting, macro",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
Three deliberate choices here. Retries are bounded by a deadline, not a loop count, so you cannot hang forever. Backoff grows on transient failures and slowly on success-path polling. And the download is a separate streamed request, which keeps large files off the JSON path.
Common Errors and How to Triage Them
Polling frequency is a real design decision. Poll every 200 ms and you generate load for no benefit; poll every five minutes and you waste wall-clock time after the render finishes.
A practical policy:
- Start with a modest interval (a few seconds) and grow it gradually — a multiplier of 1.5x per poll up to a ceiling around half a minute works well.
- Back off harder on
429and5xxresponses: double the interval and retry, treating these as capacity signals rather than job state. - Enforce a maximum total wait and raise a timeout error rather than polling forever. Renders of longer durations legitimately take longer, so set the ceiling from your own workload.
- Log the transition between states once per change, not every poll — noisy logs make real failures invisible.
A finished job response typically contains a terminal status, the job id, and a result payload with a downloadable video URL, sometimes with metadata and expiry on that URL. Fetch the file promptly after success. If the job reports failed, read the error message from the response before retrying — a validation failure will never succeed on retry, while an internal rendering error might.
Where to Go Next
Start with the minimal body, confirm one successful end-to-end run, then add duration and audio controls against the current reference for muse-video-1.0/text-to-video. The same submit-then-poll pattern transfers to other HiAPI model endpoints, so the client code you write here is reusable.
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