HappyHorse API-Dokumentation
Vollständige Anleitung zur Integration der HappyHorse 1.0 Video-Generierungs-API in Ihre Anwendungen.
Schnellstart
curl -X POST 'https://happyhorse.app/api/generate' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "happyhorse-1.0/video",
"prompt": "A cinematic shot of mountains at sunrise",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9"
}'Authentifizierung
Alle API-Anfragen erfordern eine Authentifizierung mit einem Bearer-Token im Authorization-Header.
API-Schlüssel erhalten: Ihren API-Schlüssel finden Sie auf der Seite „API Keys“ in Ihrem Dashboard. → API-Schlüssel erhalten
Authorization: Bearer YOUR_API_KEYSo funktionieren Generate und Status
HappyHorse-Videoaufgaben laufen asynchron: Erstellen Sie zuerst mit POST /api/generate eine Aufgabe, speichern Sie die task_id und fragen Sie dann GET /api/status ab, bis ein Endstatus erreicht ist.
Aufgabe erstellen
Senden Sie Prompt, Modell, Modus, Dauer und optionale Bilder an /api/generate. Bei Erfolg erhalten Sie sofort eine task_id.
Status abfragen
Nutzen Sie task_id mit /api/status. Solange der Status IN_PROGRESS ist, rendert das Video noch und response bleibt null.
Ergebnis lesen
Wenn der Status SUCCESS ist, ist data.response.resultUrls[0] die Video-URL. Bei FAILED zeigen Sie error_message an und stoppen das Polling.
Verfügbare Modelle
HappyHorse 1.0
Hochwertige KI-Videogenerierung mit HappyHorse
| Typ | Beschreibung | Dauer | Credits |
|---|---|---|---|
pro (text-to-video) | Pro-Qualität Text-zu-Video | 3-15s | 54/s (no audio) · 80/s (with audio) |
pro (image-to-video) | Pro-Qualität Bild-zu-Video | 3-15s | 54/s (no audio) · 80/s (with audio) |
std (text-to-video) | Standard-Qualität Text-zu-Video | 3-15s | 40/s (no audio) · 60/s (with audio) |
std (image-to-video) | Standard-Qualität Bild-zu-Video | 3-15s | 40/s (no audio) · 60/s (with audio) |
API-Endpunkte
Erstellt eine neue Videogenerierungsaufgabe. Das Feld model muss 'happyhorse-1.0/video' sein.
Anfragetext
Modellname, muss 'happyhorse-1.0/video' sein
Textbeschreibung des Videos (max. 2500 Zeichen). Nicht erforderlich, wenn multi_shots true ist.
Qualitätsmodus: 'pro' oder 'std' (Standard: std) Defaults to std.
Videodauer in Sekunden (3–15). Im Multi-Shot-Modus wird die Gesamtdauer aus multi_prompt abgeleitet; wenn duration explizit gesendet wird, sollte sie der Summe aller Shot-Dauern entsprechen. Defaults to 5 / sum(multi_prompt).
Ausgabe-Seitenverhältnis (16:9, 9:16, 1:1) Defaults to 16:9.
Array von Bild-URLs für Image-to-Video
Native Audiogenerierung aktivieren (Standard: true). Bei Multi-Shot-Anfragen dieses Feld bitte explizit als true oder false senden. Defaults to true.
Prompt-Treue (0-1, Standard: 0.5). Höhere Werte folgen dem Prompt enger. Defaults to 0.5.
Multi-Shot-Modus mit mehreren Prompts Defaults to false.
Array von 'prompt, duration'-Objekten für den Multi-Shot-Modus (max. 5 Shots, je max. 500 Zeichen, Dauer 1-12 s)
Array von Element-Objekten. Im Prompt @ direkt vor den Wert von name schreiben (z. B. name 'element_dog' → @element_dog im Prompt). Jedes Element: name, description, element_input_urls (2-4 Bild-URLs). Max. 3 Elemente pro Aufgabe.
Text zu Video
{
"model": "happyhorse-1.0/video",
"prompt": "A majestic eagle soaring through clouds at sunset",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9",
"sound": true
}Bild zu Video
{
"model": "happyhorse-1.0/video",
"prompt": "The character slowly turns and smiles",
"mode": "pro",
"image_urls": ["https://example.com/my-image.jpg"],
"duration": 5
}Multi-Shot-Video
{
"model": "happyhorse-1.0/video",
"mode": "pro",
"multi_shots": true,
"sound": true,
"duration": 10,
"multi_prompt": [
{ "prompt": "A woman walks into a coffee shop", "duration": 3 },
{ "prompt": "She orders a latte and sits by the window", "duration": 4 },
{ "prompt": "She looks outside and smiles", "duration": 3 }
],
"aspect_ratio": "16:9"
}Antworten
Task created successfully
{
"code": 200,
"message": "success",
"data": {
"task_id": "n92abc123hh10",
"status": "IN_PROGRESS"
}
}Prüft den Status einer Videogenerierung anhand der task_id vom Generate-Endpunkt.
Abfrageparameter
Eindeutige Aufgaben-ID vom Generate-Endpunkt (Präfix n92)
Beispielanfrage
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
-H 'Authorization: Bearer YOUR_API_KEY'Tipp: Das Feld response enthält ein resultUrls-Array. Nutzen Sie data.response.resultUrls[0] für die Video-URL.
// Extract video URL after the task is complete
const task = payload.data;
const videoUrl = task.status === "SUCCESS"
? task.response?.resultUrls?.[0]
: null;Antworten
{
"code": 200,
"message": "success",
"data": {
"task_id": "n92abc123hh10",
"status": "SUCCESS",
"consumed_credits": 400,
"created_at": "2026-04-08T10:30:00Z",
"type": "text-to-video",
"request": {
"model": "happyhorse-1.0/video",
"prompt": "A majestic eagle soaring through clouds at sunset",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9"
},
"response": {
"resultUrls": [
"https://cdn.example.com/videos/abc123.mp4"
]
},
"error_message": null
}
}Best Practices fürs Polling
Videogenerierung kann etwas dauern. Behandeln Sie Statusabfragen wie einen ruhigen Hintergrundprozess, nicht wie eine enge Schleife.
Mit kurzer Pause starten
Warten Sie vor der ersten Statusabfrage etwa 8-10 Sekunden und fragen Sie danach alle 10-20 Sekunden ab. Häufigeres Polling beschleunigt das Video nicht.
Bei Endstatus stoppen
SUCCESS und FAILED sind Endzustände. Stoppen Sie sofort, wenn einer davon erscheint, und speichern Sie die task_id für Support oder spätere Abfragen.
Client-Timeout setzen
Beenden Sie nach 10-15 Minuten das aktive Warten und lassen Sie Nutzer den Status später manuell erneut prüfen. Lassen Sie keinen Browser-Tab endlos pollen.
Bei Fehlern langsamer werden
Bei 429 oder einem temporären Netzwerkfehler warten Sie länger vor der nächsten Anfrage. Bei 401 oder 402 sollte der Nutzer API-Key oder Credits prüfen.
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function waitForHappyHorseVideo(taskId) {
const deadline = Date.now() + 15 * 60 * 1000;
let delayMs = 8000;
while (Date.now() < deadline) {
const res = await fetch(
`${BASE_URL}/api/status?task_id=${encodeURIComponent(taskId)}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
if (res.status === 429) {
await sleep(Math.min(delayMs * 2, 30000));
continue;
}
const payload = await res.json();
if (!res.ok) {
throw new Error(payload.message || `Status request failed: ${res.status}`);
}
const task = payload.data;
if (task.status === "SUCCESS") {
return task.response?.resultUrls?.[0];
}
if (task.status === "FAILED") {
throw new Error(task.error_message || "Generation failed");
}
await sleep(delayMs);
delayMs = Math.min(delayMs + 2000, 20000);
}
throw new Error("Timed out. Keep the task_id and check again later.");
}API-Playground
Testen Sie die API direkt im Browser. Ersetzen Sie YOUR_API_KEY durch Ihren echten API-Schlüssel.
Fehlercodes
| HTTP-Status | Code | Beschreibung |
|---|---|---|
| 400 Ungültige Anfrage | INVALID_PROMPT | Der Prompt ist ungültig oder leer |
| 400 Ungültige Anfrage | INVALID_DURATION | Dauer außerhalb des unterstützten Bereichs (3–15 s) |
| 400 Ungültige Anfrage | INVALID_MODEL | Modell muss 'happyhorse-1.0/video' sein |
| 401 Nicht autorisiert | INVALID_API_KEY | API-Schlüssel fehlt oder ist ungültig |
| 402 Zahlung erforderlich | INSUFFICIENT_CREDITS | Nicht genügend Credits für diesen Vorgang |
| 429 Zu viele Anfragen | RATE_LIMITED | Zu viele Anfragen, bitte langsamer |
| 500 Interner Serverfehler | INTERNAL_ERROR | Serverfehler, bitte später erneut versuchen |