Generate video via API with HappyHorse: the full async workflow

HappyHorse is the video model on Turiloop: Alibaba's audio-native generator that topped the Artificial Analysis video board, producing 1080p clips with synchronized sound from a text prompt, a still image, or reference shots. This tutorial covers the whole API surface — all four model variants, the async task workflow, polling, and the billing rules — with nothing invented: every field below is from the live docs.

The shape of the API: create, then poll

Video is not a chat completion. Generation takes real time, so the API runs as an async task: you POST a job, get a task_id back immediately, then poll until the status lands on completed and collect the file.

Step 1 — create the task:

curl -X POST "https://api.turiloop.com/v1/video/generations" \
  -H "Authorization: Bearer $TURILOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1-t2v",
    "prompt": "A corgi surfing on a sunny beach, cinematic",
    "size": "1280*720",
    "seconds": "3"
  }'

Field rules worth knowing before your first call: size takes the pixel string — "1280*720" for 720P or "1920*1080" for 1080P (an asterisk, not an x). seconds is a string, "3" through "15". Output carries a watermark by default; add "watermark": false for clean output.

Step 2 — poll the task:

curl "https://api.turiloop.com/v1/videos/{task_id}" \
  -H "Authorization: Bearer $TURILOOP_API_KEY"

Status moves through queued → in_progress → completed (or failed). On completed, `metadata.url` holds the generated MP4 — the link is time-limited, so download promptly rather than hotlinking it.

A production-shaped Python loop:

import os, time, requests

BASE = "https://api.turiloop.com/v1"
H = {"Authorization": f"Bearer {os.environ['TURILOOP_API_KEY']}"}

task = requests.post(f"{BASE}/video/generations", headers=H, json={
    "model": "happyhorse-1.1-t2v",
    "prompt": "A corgi surfing on a sunny beach, cinematic",
    "size": "1280*720",
    "seconds": "5",
    "watermark": False,
}).json()

while True:
    r = requests.get(f"{BASE}/videos/{task['task_id']}", headers=H).json()
    if r["status"] == "completed":
        print("video:", r["metadata"]["url"]); break
    if r["status"] == "failed":
        print("failed — fully auto-refunded"); break
    time.sleep(5)

The four models, and when to use each

The family's signature is that audio is native: speech, sound effects and picture come out of one stream, with lip movement matched across seven languages — nothing is dubbed on afterward. That, plus multi-shot support up to 15 seconds, is why the practical sweet spot is short narrative content: ads, product clips, short-drama beats, social cuts.

Billing: three rules that keep bills boring

1. You pay seconds × the per-second rate of the chosen resolution — 720P starts at $0.14/second on Turiloop; 1080P runs higher (current rates on the model pages). A 5-second 720P clip is about seventy cents.
2. Billing settles when the task is created, not when it finishes.
3. Failed tasks are refunded in full, automatically. You pay for output that exists.

The corollary of rule 1: develop at 720P and 3 seconds, switch to 1080P and longer cuts only for finals. Iteration is where video budgets die.

Practical notes from real integrations

• Poll at 5-second intervals, not in a tight loop — generation takes tens of seconds and hammering the status endpoint gains nothing.
• Download immediately on completion: metadata.url is time-limited by design.
• For i2v, the image URL must be publicly reachable by the API; same for every URL in r2v's images array.
• Same key, same OpenAI-style auth as the text models — one account covers chat, coding and video, pay-as-you-go with an international card, no Chinese phone number.

FAQ

How do I generate video with the HappyHorse API? POST to /v1/video/generations with a model id, prompt, size ("1280*720" or "1920*1080") and seconds ("3"–"15"); you get a task_id, then poll /v1/videos/{task_id} until completed and download the MP4 from metadata.url.

How much does HappyHorse cost per video? Seconds × the per-second rate: 720P from $0.14/second on Turiloop, so a 5-second clip runs about $0.70. Billing settles at task creation; failed tasks auto-refund in full.

Does HappyHorse output have a watermark? By default, yes. Pass "watermark": false in the creation request for clean output.

Can HappyHorse animate my own image? Yes — use happyhorse-1.1-i2v with your image as the first-frame URL, or happyhorse-1.1-r2v with up to 9 reference URLs to control style and subject.

Does it really generate audio too? Yes — audio is generated natively in the same pass as the video: speech, effects, and lip sync across seven languages including English and Chinese.