HappyHorse API-Dokumentation

Vollständige Anleitung zur Integration der HappyHorse 1.0 Video-Generierungs-API in Ihre Anwendungen.

API v1.0 Base URL: https://happyhorse.app

Schnellstart

bash
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

http
Authorization: Bearer YOUR_API_KEY

So 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.

1

Aufgabe erstellen

Senden Sie Prompt, Modell, Modus, Dauer und optionale Bilder an /api/generate. Bei Erfolg erhalten Sie sofort eine task_id.

2

Status abfragen

Nutzen Sie task_id mit /api/status. Solange der Status IN_PROGRESS ist, rendert das Video noch und response bleibt null.

3

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

HappyHorse 1.0

Hochwertige KI-Videogenerierung mit HappyHorse

TypBeschreibungDauerCredits
pro (text-to-video)Pro-Qualität Text-zu-Video3-15s54/s (no audio) · 80/s (with audio)
pro (image-to-video)Pro-Qualität Bild-zu-Video3-15s54/s (no audio) · 80/s (with audio)
std (text-to-video)Standard-Qualität Text-zu-Video3-15s40/s (no audio) · 60/s (with audio)
std (image-to-video)Standard-Qualität Bild-zu-Video3-15s40/s (no audio) · 60/s (with audio)

API-Endpunkte

Erstellt eine neue Videogenerierungsaufgabe. Das Feld model muss 'happyhorse-1.0/video' sein.

Anfragetext

Body-ParameterJSON
model:string

Modellname, muss 'happyhorse-1.0/video' sein

prompt:optional string

Textbeschreibung des Videos (max. 2500 Zeichen). Nicht erforderlich, wenn multi_shots true ist.

mode:optional string

Qualitätsmodus: 'pro' oder 'std' (Standard: std) Defaults to std.

duration:optional number

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).

aspect_ratio:optional string

Ausgabe-Seitenverhältnis (16:9, 9:16, 1:1) Defaults to 16:9.

image_urls:optional string[]

Array von Bild-URLs für Image-to-Video

sound:optional boolean

Native Audiogenerierung aktivieren (Standard: true). Bei Multi-Shot-Anfragen dieses Feld bitte explizit als true oder false senden. Defaults to true.

cfg_scale:optional number

Prompt-Treue (0-1, Standard: 0.5). Höhere Werte folgen dem Prompt enger. Defaults to 0.5.

multi_shots:optional boolean

Multi-Shot-Modus mit mehreren Prompts Defaults to false.

multi_prompt:optional array

Array von 'prompt, duration'-Objekten für den Multi-Shot-Modus (max. 5 Shots, je max. 500 Zeichen, Dauer 1-12 s)

happyhorse_elements:optional array

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

json
{
  "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

json
{
  "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

json
{
  "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

Abfrageparameter
task_id:string

Eindeutige Aufgaben-ID vom Generate-Endpunkt (Präfix n92)

Beispielanfrage

bash
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.

javascript
// 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.

javascript
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.

API-PlaygroundPOST

Fehlercodes

HTTP-StatusCodeBeschreibung
400 Ungültige AnfrageINVALID_PROMPTDer Prompt ist ungültig oder leer
400 Ungültige AnfrageINVALID_DURATIONDauer außerhalb des unterstützten Bereichs (3–15 s)
400 Ungültige AnfrageINVALID_MODELModell muss 'happyhorse-1.0/video' sein
401 Nicht autorisiertINVALID_API_KEYAPI-Schlüssel fehlt oder ist ungültig
402 Zahlung erforderlichINSUFFICIENT_CREDITSNicht genügend Credits für diesen Vorgang
429 Zu viele AnfragenRATE_LIMITEDZu viele Anfragen, bitte langsamer
500 Interner ServerfehlerINTERNAL_ERRORServerfehler, bitte später erneut versuchen