Tutorial
How to Call happyhorse-1.1/text-to-video via the HiAPI API: Working curl and Python Examples
Request shape, async polling, and native audio handling for a working integration
On this page
What this integration covers
This guide walks you through calling happyhorse-1.1/text-to-video through the HiAPI unified API. By the end, you'll have a working request that submits a text prompt, polls for completion, and saves the generated video along with its native audio track. We'll start with the request shape so you understand the payload before writing any code, then move to a copy-paste curl call, explain the asynchronous polling pattern that video generation requires, and finally port everything to Python with basic error handling. No prior experience with video APIs is assumed; you just need a HiAPI API key and a terminal or Python environment. The goal is a minimal but complete integration you can adapt to your own pipeline.
Request shape for happyhorse-1.1/text-to-video
Before making a call, it helps to understand the fields that make up a text-to-video request. The endpoint accepts a JSON payload containing at minimum the model identifier and your text prompt. Other common fields control output dimensions and duration, but the exact parameter names and accepted values should be confirmed against the model's documentation on HiAPI. A valid payload will generally look like this:
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "A slow pan across a misty forest at sunrise"
}
Keep the payload flat and use only the fields the model documents. Unrecognized fields or malformed types are the most common cause of rejected requests. When in doubt, start with the smallest payload that includes only model and prompt, then add optional parameters one at a time so you can isolate any issues.
First request with curl
With your payload ready, you can submit a job using curl. You'll send a POST request with a JSON body and your API key in the Authorization header. The response will typically include an identifier for the job, which you'll use later to poll for status. Here's a working example:
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "A slow pan across a misty forest at sunrise"
}'
Replace $HIAPI_API_KEY with your actual key or export it in your shell. The response will be JSON containing an id field (or similarly named identifier) and a status indicating the job was accepted. Read the response carefully: if the status is not an accepted state, inspect the error message before proceeding. Do not assume the video is ready at this point; the job has only been queued.
Handling async polling
Video generation is not instantaneous, so HiAPI returns a job identifier rather than the finished video in the initial response. You need to poll a status endpoint until the job reaches a terminal state. The general pattern is: submit the job, capture the ID, then repeatedly request the job status with a short delay between attempts. Stop when the status indicates success or failure. Here's the logic in pseudocode:
- Submit the job and read the job
id. - Wait a few seconds.
- Request the job status using the
id. - If the status is "completed" or "succeeded", retrieve the output URL and exit the loop.
- If the status is "failed", log the error and exit.
- Otherwise, wait again and repeat, up to a reasonable maximum number of attempts.
Avoid polling too aggressively. A delay of several seconds between attempts is usually sufficient for video jobs. Also, do not assume a single blocking response will ever contain the final video; the asynchronous model is intentional and consistent across long-running generation tasks.
Native audio in the output
Videos generated by happyhorse-1.1/text-to-video carry native audio as part of the output. When the job completes, the response will point you to the generated video file, which already includes the audio track. You do not need to generate or fetch audio separately. To save and validate the result, download the video file from the provided URL and preserve the container format. If you're processing the file programmatically, verify that the audio stream is present, for example by inspecting the file with a media tool. Do not strip or re-encode the audio unless your downstream pipeline requires it, as that can degrade quality or remove the track entirely. Treat the returned file as a complete audiovisual asset.
The same request in Python
Porting the curl call to Python is straightforward: reuse the same JSON payload and add a polling loop. The example below uses requests, waits between attempts, and raises on failure. Replace the endpoint paths and status field names with those documented for happyhorse-1.1/text-to-video on HiAPI.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "A slow pan across a misty forest at sunrise",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("Video ready:", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "generation failed"))
time.sleep(5)
else:
raise TimeoutError("polling timed out")
This follows the same poll-until-complete logic described earlier. Use raise_for_status() to surface HTTP errors early, and keep the sleep interval reasonable to avoid unnecessary requests.
Troubleshooting common failures
Most integration issues fall into a few categories. Malformed payloads, such as missing the model field or using the wrong JSON types, will be rejected immediately; double-check your JSON against the model documentation. Polling too aggressively can cause rate limiting or unnecessary load; increase your sleep interval. Misreading the initial response as the final video is another common mistake; always poll until a terminal state. Authentication errors usually mean a missing or malformed Authorization header, so verify your API key is exported correctly. Finally, if the job fails after polling, inspect the error message in the status response; it often points to an invalid prompt or unsupported parameter. Fix these issues and retry with the smallest valid payload first.
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