HappyHorse API Belgeleri
HappyHorse 1.0 Video Oluşturma API’sini uygulamalarınıza entegre etmek için eksiksiz kılavuz.
Hızlı başlangıç
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
Authorization: Bearer YOUR_API_KEYGenerate 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.
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.
Durumu sorgula
task_id ile /api/status çağırın. status IN_PROGRESS iken video hâlâ işlenir ve response null kalır.
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 ile yüksek kaliteli yapay zekâ video üretimi
| Tür | Açıklama | Süre | Kredi |
|---|---|---|---|
pro (text-to-video) | Pro kalite metinden videoya | 3-15s | 54/s (no audio) · 80/s (with audio) |
pro (image-to-video) | Pro kalite görüntüden videoya | 3-15s | 54/s (no audio) · 80/s (with audio) |
std (text-to-video) | Standart kalite metinden videoya | 3-15s | 40/s (no audio) · 60/s (with audio) |
std (image-to-video) | Standart kalite görüntüden videoya | 3-15s | 40/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
Model adı; 'happyhorse-1.0/video' olmalıdır
Oluşturulacak videonun metin açıklaması (en fazla 2500 karakter). multi_shots true ise zorunlu değil.
Kalite modu: 'pro' veya 'std' (varsayılan: std) Defaults to std.
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).
Çıkış en-boy oranı (16:9, 9:16, 1:1) Defaults to 16:9.
Görüntüden videoya görevleri için görüntü URL dizisi
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.
İstem bağlılığı (0-1, varsayılan: 0.5). Yüksek değerler isteme daha sadık kalır. Defaults to 0.5.
Birden fazla istemle çok planlı mod Defaults to false.
Çok planlı mod için 'prompt, duration' nesne dizisi
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
{
"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
{
"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
{
"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
generate’ın döndürdüğü benzersiz görev kimliği (n92 öneki)
Örnek istek
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.
// 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.
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.
Hata kodları
| HTTP durumu | Kod | Açıklama |
|---|---|---|
| 400 Hatalı istek | INVALID_PROMPT | İstem geçersiz veya boş |
| 400 Hatalı istek | INVALID_DURATION | Süre desteklenen aralığın dışında (3–15 sn) |
| 400 Hatalı istek | INVALID_MODEL | Model 'happyhorse-1.0/video' olmalıdır |
| 401 Yetkisiz | INVALID_API_KEY | API anahtarı eksik veya geçersiz |
| 402 Ödeme gerekli | INSUFFICIENT_CREDITS | Bu işlem için yeterli kredi yok |
| 429 Çok fazla istek | RATE_LIMITED | Çok fazla istek; lütfen yavaşlayın |
| 500 Sunucu hatası | INTERNAL_ERROR | Sunucu hatası; daha sonra tekrar deneyin |