HappyHorse 1.1 Text-zu-Video-API über HiAPI aufrufen: ein praxistaugliches curl- und Python-Tutorial

HappyHorse 1.1 ist das Text-zu-Video-Modell von Alibaba: Es unterstützt 720p-/1080p-Videoclips mit 3–15 Sekunden Länge und erzeugt bei einem einzigen Aufruf natives Audio (kein separater Musikschritt erforderlich). HiAPI stellt dieses Modell über denselben einheitlichen asynchronen Endpunkt bereit wie alle anderen generativen Modelle. Wenn Sie also bereits Bildmodelle über /v1/tasks aufgerufen haben, ändern sich nur die Modell-ID und einige input-Felder.

Diese Seite bietet das Minimum, das für die Auslieferung einer funktionierenden Integration nötig ist: das exakte Schema, direkt kopierbares curl, einen Python-Polling-Client und das Callback-Muster für die Produktion. Außerdem werden zwei weniger offensichtliche Dinge ausdrücklich genannt, die das Modell nicht akzeptiert (ein audio-Schalter und ein seed), damit Sie keine Anfrage wegen eines 400 verschwenden.

Voraussetzungen. Holen Sie sich einen Schlüssel aus der HiAPI-Konsole und exportieren Sie ihn als HIAPI_API_KEY. Jede Anfrage wird über Authorization: Bearer sk-… authentifiziert; zur Auffrischung siehe Authentication.

Endpunkt und Anforderungsstruktur

Alles läuft über denselben Endpunkt:

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Der Anforderungskörper hat drei Schlüssel auf oberster Ebene:

• model — happyhorse-1.1/text-to-video (die wörtliche Modell-ID — der Schrägstrich muss erhalten bleiben).
• input — modellspezifische Felder. Für HappyHorse 1.1 T2V:
  • prompt (String, erforderlich) — beschreibt den Videoclip.
  • resolution (720p | 1080p, Standard 1080p).
  • aspect_ratio (16:9 | 9:16 | 3:4 | 4:3 | 4:5 | 5:4 | 1:1 | 9:21 | 21:9, Standard 16:9).
  • duration (Ganzzahl, 3–15, Standard 5). Die Kosten steigen mit der Sekundenzahl.
• callback (optional, Objekt) — callback.url HTTPS-Endpunkt + callback.when: "final". HiAPI sendet für jede Aufgabe genau einmal das Endergebnis an diese Adresse.

Zwei Dinge, die funktionieren zu sollen scheinen, es aber nicht tun:

• ❌ Kein audio-Feld. Audio wird nativ mit dem Video erzeugt; es gibt keinen Schalter. Wenn Sie "audio": true senden, wird additional properties 'audio' not allowed zurückgegeben.
• ❌ Kein seed-Feld. Ebenfalls 400. Wenn Sie jetzt Determinismus über Batches benötigen, erzeugen Sie mehrere Varianten und wählen Sie aus — es gibt keinen einstellbaren seed-Hebel.

Ein minimaler gültiger Anforderungskörper:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "A golden retriever running on a beach, slow motion, gentle waves, warm sunset tones",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}

Minimales lauffähiges Beispiel: curl

Aufgabe erstellen — die Antwort kommt sofort zurück und enthält nur eine taskId:

curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A snow mountain lake in morning mist, slow camera push-in, warm cinematic light",
      "resolution": "1080p",
      "aspect_ratio": "16:9",
      "duration": 5
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KW3..."},"message":"success"}

Dann abfragen, bis ein Endzustand erreicht ist:

TASK_ID=tk-hiapi-01KW3...

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "happyhorse-1.1/text-to-video",
#     "output": [
#       {"type":"video","url":"https://temp.hiapi.ai/.../...-0.mp4","expireAt":1783130616}
#     ],
#     ...
#   }
# }

Die mp4-URL ist temporär (expireAt ist ein Unix-Zeitstempel etwa 7 Tage in der Zukunft). Laden Sie sie sofort nach erfolgreichem Abschluss der Aufgabe herunter und speichern Sie sie dauerhaft — kein Hotlinking. Wenn Sie stattdessen die langfristige Speicherung durch HiAPI bevorzugen, lesen Sie die Dokumentation zu Output Storage, um zu erfahren, wie Sie Ausgaben vom temporären in den dauerhaften Speicher überführen.

Python: ein kleiner Client in Produktionsform

Ein echter Client braucht drei Dinge: create_task, das eine ID zurückgibt, wait_task, das mit einer Frist abfragt, und einen Download-Schritt. Dieses Grundgerüst enthält alle drei und kommt dem Startpunkt der Python-SDK-Seite von HiAPI nahe — halten Sie es klein und erweitern Sie es daraus.

# pip install requests
import os, time, json, requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def create_task(prompt: str, *, resolution="1080p", aspect_ratio="16:9", duration=5) -> str:
    body = {
        "model": "happyhorse-1.1/text-to-video",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
        },
    }
    r = requests.post(API_BASE, headers={**HEADERS, "Content-Type": "application/json"},
                      data=json.dumps(body), timeout=60)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"create failed: {data}")
    return data["data"]["taskId"]


def wait_task(task_id: str, *, timeout_s: int = 600, poll: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


def download(url: str, path: str) -> None:
    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(1 << 14):
                f.write(chunk)


if __name__ == "__main__":
    task_id = create_task(
        "A neon street at night after rain, reflections on the ground, "
        "cyberpunk mood, slow pan",
        resolution="720p", aspect_ratio="9:16", duration=5,
    )
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    download(url, "out.mp4")
    print("saved out.mp4")

Einige Hinweise für die Produktion:

• Statusfeld. Behandeln Sie jeden Wert außer success oder fail als in Bearbeitung (die Plattform verwendet derzeit handling).
• raise_for_status reicht nicht. Bei bestimmten Validierungsfehlern gibt HiAPI HTTP 200 zurück, aber code ist nicht 200 — prüfen Sie daher immer auch data["code"]. Bei einer neuen Integration ist 401 permission_denied am häufigsten, was bedeutet, dass das Bearer-Token falsch oder fehlend ist — exportieren Sie HIAPI_API_KEY erneut und bestätigen Sie ihn in der Konsole.

Produktion: Callbacks statt Polling bevorzugen

Für alles, was über einen Schnelleinstieg hinausgeht, geben Sie HiAPI einen Webhook, den es beim Abschluss der Aufgabe aufruft:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "A snow mountain lake in morning mist, slow camera push-in, warm cinematic light",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Stellen Sie sicher, dass Ihr Callback-Handler Folgendes tut:

• Nach taskId deduplizieren. success und fail sind beide Endzustände — Ihr Dienst sollte den zweifachen Empfang derselben taskId als No-Op behandeln (idempotentes Schreiben mit taskId als Schlüssel).
• Schnell 2xx zurückgeben. Legen Sie die schwere Arbeit (mp4 herunterladen, persistieren, Benutzer benachrichtigen) in eine Warteschlange. Der Webhook-Handler sollte innerhalb von Sekunden bestätigen.
• GET /v1/tasks/:id als Fallback beibehalten. Wenn ein Webhook verloren geht (Deployment, Netzwerkausfall), ist ein Abgleich-Job, der hängende Aufgaben per ID abruft und denselben Handler anwendet, das einfachste Sicherheitsnetz.

Wenn Sie einen Weg wählen müssen: Polling eignet sich für Einmalskripte und lokales Debugging, während überall dort, wo echter Datenverkehr herrscht, Callbacks verwendet werden sollten.

Die richtigen Parameter wählen (resolution × aspect_ratio × duration)

Anforderung	resolution	aspect_ratio	duration
Hochformat-Clip für soziale Medien, geringste Kosten	720p	9:16	5
Quadratische Vorschau / Thumbnail-Schleife	720p	1:1	3
Querformat-Erzählung / Werbeeinstellung	1080p	16:9	5–8
Breitbild-Key-Visual-Clip	1080p	21:9	8–12

Die Kosten steigen mit Auflösung und Dauer — die genaue Preisgestaltung pro Sekunde finden Sie unter HiAPI-Preise. Wenn Sie sich bei den richtigen Werten unsicher sind, lassen Sie sie weg: resolution ist standardmäßig 1080p, aspect_ratio ist standardmäßig 16:9, duration ist standardmäßig 5.

Häufig gestellte Fragen

Hat HappyHorse 1.1 Text-zu-Video einen seed-Parameter? Nein. Die API lehnt seed mit additional properties 'seed' not allowed ab. Wenn Sie mehrere Optionen zur Auswahl benötigen, reichen Sie mehrere Aufgaben mit demselben prompt ein — verschiedene Läufe erzeugen auf natürliche Weise Unterschiede.

Wie schalte ich Audio ein oder aus? Das können Sie nicht — HappyHorse 1.1 erzeugt die Tonspur nativ im selben Aufruf. Es gibt keinen audio-Schalter im Schema; wenn Sie einen senden, wird ein 400 zurückgegeben. Wenn Sie einen stummen Clip benötigen, entfernen Sie das Audio in der Nachbearbeitung.

Welche Dauern sind gültig? Ganzzahlen von 3 bis 15 (Sekunden). Werte außerhalb dieses Bereichs geben duration: minimum: got 0, want 3 oder duration: maximum: got 20, want 15 zurück. Dezimalzahlen werden ebenfalls abgelehnt (der Feldtyp ist Ganzzahl).

Welche Seitenverhältnisse werden unterstützt? Neun: 16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9. Standard ist 16:9.

Wie lange bleibt output[].url gültig? Etwa eine Woche — die Antwort enthält einen Unix-Zeitstempel expireAt. Laden Sie das mp4 sofort herunter und hosten Sie es erneut (S3, R2, Ihr CDN) oder überführen Sie es über die Output Storage API in dauerhaften Speicher.

Was ist mit Bild-zu-Video? HappyHorse 1.1 hat eine I2V-Variante am selben Endpunkt — siehe HappyHorse 1.1 I2V. Gleiche Authentifizierung, gleicher asynchroner Lebenszyklus, anderes input-Schema.

Wo finde ich die vollständige asynchrone API-Referenz? Den Anforderungs-Umschlag finden Sie unter Create Task, den Polling-Endpunkt unter Get Task Detail und das kanonische Eingabeschema auf der HappyHorse 1.1 T2V-Modellseite. Wenn Sie bei null beginnen, führt Sie der Quickstart end-to-end durch Ihren ersten Aufruf.