API dokümantasyonu
API dokümantasyonu
Tüm AI özelliklerini API anahtarıyla çağırın, kullanım başına ödeme, birkaç satır kodla entegrasyon.
Kimlik doğrulama
Tüm API istekleri Authorization başlığı içermelidir.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxAPI anahtarınızı konsolda „API Anahtarları" sayfasından alın. Hesap başına bir anahtar. Sıfırlama konsolda; eski anında geçersiz olur.
Görev oluştur
POST
https://nsfwrouter.xyz/api/v1/tasks/create
GPU kümesine AI görevi gönderin. Görevler asenkron, ID döndürür. Sonuçlar API veya Webhook ile.
İstek parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| tool_id | int | Evet | Araç ID, araç listesinden |
| params | object | Evet | Görev parametreleri, JSON nesne, alanlar araca bağlı |
| webhook_url | string | Hayır | Tamamlanma bildirimi için callback URL |
| priority | int | Hayır | Görev önceliği 1-10, varsayılan 5 |
| idempotency_key | string | Hayır | Idempotency anahtarı, tekrarları önler |
| execution_options | object | Hayır | Yürütme seçenekleri, JSON nesne |
İstek örneği
curl -X POST https://nsfwrouter.xyz/api/v1/tasks/create \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool_id": 1,
"params": {
"image": "https://example.com/photo.jpg",
"prompt": "a beautiful landscape"
},
"webhook_url": "https://your-server.com/webhook"
}'Yanıt örneği
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}Bakiye çağrıdan önce kontrol edilir. Yetersiz = hata insufficient_coins. Jetonlar başarılı gönderimde düşülür.
Görev sorgula
GET
https://nsfwrouter.xyz/api/v1/tasks/query
ID'ye göre detay ve durum sorgula. İşlem sırasında durum GPU kümesinden alınır. 10 sn içinde tekrar sorgular DB cache döndürür.
Sorgu parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| id | int | Evet | Görev ID |
Yanıt örneği
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}
}Görev durum değerleri
| status | Anlam |
|---|---|
| 0 | İşleniyor |
| 1 | Tamamlandı |
| -1 | İptal edildi |
| -2 | Başarısız |
Görev listesi
GET
https://nsfwrouter.xyz/api/v1/tasks
Hesap görevlerinin sayfalı sorgusu, araç, durum ve dönem filtreleriyle.
Sorgu parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| page | int | Hayır | Sayfa numarası, varsayılan 1 |
| page_size | int | Hayır | Sayfa boyutu, varsayılan 20, max 50 |
| tool_id | int | Hayır | Araca göre filtre |
| status | int | Hayır | Duruma göre filtre (0/1/-1/-2) |
| days | int | Hayır | Gün olarak dönem, varsayılan 30 |
Yanıt örneği
{
"code": 0,
"message": "success",
"data": {
"list": [
{
"id": 123,
"tool_id": 1,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"error": null,
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
},
{
"id": 122,
"tool_id": 3,
"status": 0,
"task_output_json": [],
"error": null,
"consume_coins": 10,
"created_at": 1718199000,
"completed_at": 0
}
],
"page": 1,
"page_size": 20
}
}task_output_json alan açıklamaları
| Alan | Tip | Açıklama |
|---|---|---|
| type | string | Sonuç tipi: image veya video |
| url | string | Sonuç dosyası için CDN URL |
| file_name | string | Dosya adı |
| file_size | int | Dosya boyutu (byte) |
| mime_type | string | MIME tipi, örn. image/png, video/mp4 |
| width | int | Genişlik (piksel) |
| height | int | Yükseklik (piksel) |
Hesap bakiyesi
GET
https://nsfwrouter.xyz/api/v1/account/balance
Jeton bakiyesini, toplam yükleme ve toplam tüketimi kontrol edin.
Yanıt örneği
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook callback
webhook_url belirtilirse, tamamlandığında, başarısız olduğunda veya iptal edildiğinde POST gönderilir. Body JSON.
Callback istek başlıkları
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0Callback istek body
{
"event": "task.finished",
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}Sunucunuz HTTP 2xx döndürmeli. Non-2xx veya timeout (10 sn) durumunda sistem 5 kez exponansiyel backoff ile yeniden dener.
Hata kodları
Tüm hata yanıtları birleşik format kullanır: {"code": kod, "message": "tanımlayıcı", "data": {}}
| Hata kodu | message | Açıklama |
|---|---|---|
| 20001 | api_key_required | API anahtarı belirtilmedi |
| 20001 | invalid_api_key | Geçersiz API anahtarı |
| 20001 | ip_not_allowed | IP whitelist'te değil |
| 20001 | permission_denied | Erişim reddedildi |
| 30001 | tool_not_found | Araç bulunamadı |
| 30001 | task_not_found | Görev bulunamadı |
| 30001 | insufficient_coins | Yetersiz jeton bakiyesi |
| 30001 | task_submit_failed | Görev gönderimi başarısız |
| 30001 | task_query_failed | Görev sorgusu başarısız |
| 30001 | task_already_exists | Görev zaten mevcut (idempotency) |
| 40001 | tool_id_required | tool_id parametresi eksik |
| 40001 | param_error | Parametre hatası |
| 40001 | webhook_url_invalid | Geçersiz webhook_url formatı |
| 40001 | params_must_be_json_object_or_array | params JSON nesne veya dizi olmalı |
| 40001 | execution_options_must_be_json_object_or_array | execution_options JSON nesne veya dizi olmalı |
Hata kodu aralıkları
| Aralık | Kategori |
|---|---|
| 1xxxx | Sistem hatası |
| 2xxxx | Kimlik doğrulama hatası |
| 3xxxx | İş mantığı hatası |
| 4xxxx | Parametre hatası |
| 5xxxx | Harici bağımlılık hatası |