HappyHorse API Belgeleri

HappyHorse 1.0 Video Oluşturma API’sini uygulamalarınıza entegre etmek için eksiksiz kılavuz.

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

Hızlı başlangıç

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"
  }'

Kimlik doğrulama

Tüm API istekleri Authorization başlığında Bearer jetonu gerektirir.

API anahtarınızı alın: API anahtarınızı kontrol panelindeki API Keys sayfasından alabilirsiniz. → API anahtarınızı alın

http
Authorization: Bearer YOUR_API_KEY

Generate ve Status nasıl çalışır

HappyHorse video görevleri asenkrondur: POST /api/generate ile görev oluşturun, dönen task_id değerini saklayın ve son duruma ulaşana kadar GET /api/status ile kontrol edin.

1

Görev oluştur

Prompt, model, mode, duration ve isteğe bağlı görselleri /api/generate endpoint'ine gönderin. Başarılı yanıt hemen task_id döndürür.

2

Durumu sorgula

task_id ile /api/status çağırın. status IN_PROGRESS iken video hâlâ işlenir ve response null kalır.

3

Sonucu oku

status SUCCESS olduğunda data.response.resultUrls[0] video URL'sidir. FAILED olursa error_message gösterin ve polling'i durdurun.

Kullanılabilir modeller

HappyHorse 1.0

HappyHorse 1.0

HappyHorse ile yüksek kaliteli yapay zekâ video üretimi

TürAçıklamaSüreKredi
pro (text-to-video)Pro kalite metinden videoya3-15s54/s (no audio) · 80/s (with audio)
pro (image-to-video)Pro kalite görüntüden videoya3-15s54/s (no audio) · 80/s (with audio)
std (text-to-video)Standart kalite metinden videoya3-15s40/s (no audio) · 60/s (with audio)
std (image-to-video)Standart kalite görüntüden videoya3-15s40/s (no audio) · 60/s (with audio)

API uç noktaları

Yeni bir video oluşturma görevi başlatır. model alanı 'happyhorse-1.0/video' olmalıdır.

İstek gövdesi

Gövde parametreleriJSON
model:string

Model adı; 'happyhorse-1.0/video' olmalıdır

prompt:optional string

Oluşturulacak videonun metin açıklaması (en fazla 2500 karakter). multi_shots true ise zorunlu değil.

mode:optional string

Kalite modu: 'pro' veya 'std' (varsayılan: std) Defaults to std.

duration:optional number

Video süresi saniye cinsinden (3–15). Çok planlı modda nihai süre multi_prompt toplamından türetilir; duration alanını açıkça gönderiyorsanız plan sürelerinin toplamıyla aynı olmalıdır. Defaults to 5 / sum(multi_prompt).

aspect_ratio:optional string

Çıkış en-boy oranı (16:9, 9:16, 1:1) Defaults to 16:9.

image_urls:optional string[]

Görüntüden videoya görevleri için görüntü URL dizisi

sound:optional boolean

Yerel ses üretimini etkinleştir (varsayılan: true). Çok planlı isteklerde bu alanı true veya false olarak açıkça gönderin. Defaults to true.

cfg_scale:optional number

İstem bağlılığı (0-1, varsayılan: 0.5). Yüksek değerler isteme daha sadık kalır. Defaults to 0.5.

multi_shots:optional boolean

Birden fazla istemle çok planlı mod Defaults to false.

multi_prompt:optional array

Çok planlı mod için 'prompt, duration' nesne dizisi

happyhorse_elements:optional array

Eleman nesneleri dizisi. Istemde ilgili elemanin name degerinin basina @ yazin (or. name 'element_dog' → @element_dog). Her eleman: name, description, element_input_urls (2-4 gorsel URL). Gorev basina en fazla 3 eleman.

Metinden videoya

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
}

Görüntüden videoya

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
}

Çok planlı 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"
}

Yanıtlar

Task created successfully

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "IN_PROGRESS"
  }
}

generate uç noktasının döndürdüğü task_id ile video oluşturma durumunu kontrol eder.

Sorgu parametreleri

Sorgu parametreleri
task_id:string

generate’ın döndürdüğü benzersiz görev kimliği (n92 öneki)

Örnek istek

bash
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

İpucu: response alanı resultUrls dizisini içerir. Video URL’si için data.response.resultUrls[0] kullanın.

javascript
// Extract video URL after the task is complete
const task = payload.data;
const videoUrl = task.status === "SUCCESS"
  ? task.response?.resultUrls?.[0]
  : null;

Yanıtlar

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

Polling için iyi uygulamalar

Video oluşturma biraz zaman alabilir; durum kontrollerini sıkı bir döngü yerine sakin bir arka plan işi gibi ele alın.

Kısa bir bekleme ile başlayın

İlk durum kontrolünden önce yaklaşık 8-10 saniye bekleyin, sonra 10-20 saniyede bir kontrol edin. Daha sık polling videoyu hızlandırmaz.

Son durumlarda durun

SUCCESS ve FAILED son durumlardır. Bunlardan birini görür görmez polling'i durdurun ve destek ya da sonraki sorgular için task_id değerini saklayın.

İstemci timeout kullanın

10-15 dakika sonra aktif beklemeyi durdurun ve kullanıcının durumu daha sonra manuel kontrol etmesine izin verin. Bir tarayıcı sekmesini sonsuza kadar polling yapar halde bırakmayın.

Hatalarda yavaşlayın

429 veya geçici bir ağ hatası alırsanız, sonraki istekten önce daha uzun bekleyin. 401 veya 402 için kullanıcıdan API anahtarını ya da kredileri düzeltmesini isteyin.

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 oyun alanı

API’yi doğrudan tarayıcıdan test edin. YOUR_API_KEY’i gerçek anahtarınızla değiştirin.

API oyun alanıPOST

Hata kodları

HTTP durumuKodAçıklama
400 Hatalı istekINVALID_PROMPTİstem geçersiz veya boş
400 Hatalı istekINVALID_DURATIONSüre desteklenen aralığın dışında (3–15 sn)
400 Hatalı istekINVALID_MODELModel 'happyhorse-1.0/video' olmalıdır
401 YetkisizINVALID_API_KEYAPI anahtarı eksik veya geçersiz
402 Ödeme gerekliINSUFFICIENT_CREDITSBu işlem için yeterli kredi yok
429 Çok fazla istekRATE_LIMITEDÇok fazla istek; lütfen yavaşlayın
500 Sunucu hatasıINTERNAL_ERRORSunucu hatası; daha sonra tekrar deneyin