Kılavuzlar

Hızlı başlangıç

Eşzamansız bir Görev oluşturun ve yoklama, tamamlama, hata ve geri çağırmaları yönetin.

RunAPI, eş zamansız görüntü, video, ses ve müzik üretimi için Görevler kullanır. Bir oluşturma isteği hızla döner; uygulamanız ardından Görevi yoklar veya o uç noktanın API Başvurusu’nda listelenen geri çağırma olaylarını alır.

Bir Görev Oluştur

Katalog’dan bir model ve uç nokta seçin, ardından uç noktanın gerekli girdilerini gönderin. Bu örnek bir Flux 2 metinden görüntüye Görevi başlatır:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

Kabul edilen asenkron bir istek, Görev tanımlayıcısıyla birlikte 202 Accepted döndürür:

JSON

{
  "id": "task_id",
  "status": "processing"
}

id‘yi uygulama kaydınızla birlikte saklayın. Bu, yoklama, destek ve geri çağırma uzlaştırması için kullanılan kararlı tanımlayıcıdır.

Yinelenen Görev oluşturmayı önleyin

Görev oluşturma uç noktaları, 512 karaktere kadar opak bir değer içeren isteğe bağlı bir Idempotency-Key başlığını kabul eder. Her mantıksal Görev için bir değer oluşturun ve isteğin kabul edilip edilmediğini öğrenene kadar bu değeri istekle birlikte saklayın.

Bir zaman aşımı veya bağlantı hatası sonucu belirsiz bırakırsa, aynı anahtarla tam olarak aynı Görev oluşturma isteğini yeniden deneyin. RunAPI, ikinci bir Görev oluşturmak ve ücretlendirmek yerine orijinal Görevi döndürür. Farklı bir Görev oluşturma isteğiyle aynı anahtarın yeniden kullanılması 409 Conflict döndürür. Kasıtlı olarak yeni bir Görev için yeni bir anahtar oluşturun ve bu anahtar olarak X-Client-Request-Id kullanmayın.

Kesintiye uğramış eş zamanlı bir isteği kurtarın

Yavaş eş zamanlı uç noktalar normalde bağlantıyı açık tutar ve daha önce olduğu gibi aynı terminal yanıtını döndürür. Mevcut entegrasyonlar için yoklama değişikliği gerekmez.

Kasıtlı olarak daha kısa bir bağlantı bütçesi için Prefer: wait=N gönderin. Görev bu açık bütçe sonunda hâlâ çalışıyorsa RunAPI, aynı Görev id‘si, kurtarma için opak bir Location URL’si ve önerilen sorgu gecikmesi için Retry-After içeren 202 Accepted döndürür. Bir sonuç URL’si oluşturmak yerine Location‘ı tam olarak takip edin. Tamamlanan bir Görev Sonucu terminal HTTP durumunu, izin verilen başlıkları, içerik türünü ve gövdeyi korur; response.body‘yi her zaman JSON olmayan response.content_type‘a göre çözün.

Görev Yoklama

Görev tanımlayıcısını aynı uç nokta yoluna ekleyin:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

status processing olduğu sürece devam edin. Sürekli yoklama yapmak yerine istekler arasında sınırlı geri çekilme kullanın. Bir Görev, durumu completed veya failed olduğunda terminal hale gelir.

Tamamlamayı işle

completed yanıtı Görev id‘sini, terminal status değerini ve uç noktaya özgü sonuç alanlarını içerir. İhtiyaç duyduğunuz sonucu saklayın ve yoklamayı durdurun. Her medya uç noktasının aynı alanları döndürdüğünü varsaymak yerine tam sonuç yapısı için ilgili uç noktanın API başvurusuna bakın.

Başarısızlığı işle

failed yanıtı Görev id‘sini, terminal status değerini ve mevcut olduğunda RunAPI tarafından oluşturulan bir error içerir. Yoklamayı durdurun, tanımlayıcıyı ve hatayı kaydedin; yalnızca uygulamanız hatayı geçici olarak sınıflandırdığında yeniden deneyin. Yeniden deneme yeni bir Görev tanımlayıcısı oluşturur.

Geri çağırma alma

RunAPI’nin ilgili uç nokta için belgelenmiş geri çağırma olaylarını göndermesini istiyorsanız oluşturma isteğine genel erişime açık bir HTTPS callback_url ekleyin:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Her geri çağırma gövdesi, uç noktanın API Başvurusu’ndaki bir yaşam döngüsü olayıyla eşleşir ve yalnızca yoklamaya özgü faturalandırma ayrıntılarını dışarıda bırakır. Terminal geri çağırmaları, terminal yoklama yanıtlarıyla aynı sonuç alanlarını içerir; bazı uç noktalar ayrıca belgelenmiş processing geri çağırmaları da gönderir. Başarılı bir HTTP yanıtını hızla döndürün ve teslimat geciktiğinde ya da geri çağırma işleyiciniz kullanılamadığında mutabakat için yoklamayı kullanılabilir bırakın.

Geri Çağırma Sırrı oluşturmak, imzaları doğrulamak ve yeniden denemeleri güvenli biçimde işlemek için Geri çağırmalar bölümünü okuyun.