API dokumentácia
API dokumentácia
Volajte všetky AI funkcie cez API kľúč, platba za použitie, integrácia v pár riadkoch.
Autentifikácia
Všetky API požiadavky musia obsahovať hlavičku Authorization.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxZískajte API kľúč na stránke „API kľúče" v konzole. Jeden kľúč na účet. Reset v konzole; starý sa okamžite zneplatní.
Vytvorenie úlohy
POST
https://nsfwrouter.xyz/api/v1/tasks/create
Odošlite AI úlohu do GPU clustra. Úlohy sú asynchrónne, vrátia ID. Výsledky cez API alebo Webhook.
Parametre požiadavky
| Parameter | Typ | Povinný | Popis |
|---|---|---|---|
| tool_id | int | Áno | ID nástroja, zo zoznamu |
| params | object | Áno | Parametre úlohy, JSON objekt, polia závisia od nástroja |
| webhook_url | string | Nie | URL callback pre notifikáciu o dokončení |
| priority | int | Nie | Priorita úlohy 1-10, predvolené 5 |
| idempotency_key | string | Nie | Kľúč idempotencie, zabraňuje duplicitám |
| execution_options | object | Nie | Možnosti vykonania, JSON objekt |
Príklad požiadavky
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"
}'Príklad odpovede
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}Zostatok sa kontroluje pred volaním. Nedostatok mincí = chyba insufficient_coins. Mince sa strhávajú pri úspešnom odoslaní.
Dotaz na úlohu
GET
https://nsfwrouter.xyz/api/v1/tasks/query
Dotaz na detaily a status podľa ID. Počas spracovania sa status berie z GPU clustra. Opakované dotazy do 10 sekúnd vracajú DB cache.
Parametre dotazu
| Parameter | Typ | Povinný | Popis |
|---|---|---|---|
| id | int | Áno | ID úlohy |
Príklad odpovede
{
"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
}
}
}Hodnoty statusu úlohy
| status | Význam |
|---|---|
| 0 | Spracováva sa |
| 1 | Dokončené |
| -1 | Zrušené |
| -2 | Chyba |
Zoznam úloh
GET
https://nsfwrouter.xyz/api/v1/tasks
Stránkovaný dotaz na úlohy účtu, s filtrami na nástroj, status a obdobie.
Parametre dotazu
| Parameter | Typ | Povinný | Popis |
|---|---|---|---|
| page | int | Nie | Číslo stránky, predvolené 1 |
| page_size | int | Nie | Veľkosť stránky, predvolené 20, max 50 |
| tool_id | int | Nie | Filtrovať podľa nástroja |
| status | int | Nie | Filtrovať podľa statusu (0/1/-1/-2) |
| days | int | Nie | Obdobie v dňoch, predvolené 30 |
Príklad odpovede
{
"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
}
}Popis polí task_output_json
| Pole | Typ | Popis |
|---|---|---|
| type | string | Typ výsledku: image alebo video |
| url | string | CDN URL súboru výsledku |
| file_name | string | Názov súboru |
| file_size | int | Veľkosť (bajty) |
| mime_type | string | MIME typ, napr. image/png, video/mp4 |
| width | int | Šírka (pixely) |
| height | int | Výška (pixely) |
Zostatok účtu
GET
https://nsfwrouter.xyz/api/v1/account/balance
Skontrolujte zostatok mincí, celkové dobitie a celkovú spotrebu.
Príklad odpovede
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook callback
Ak je zadaný webhook_url, po dokončení, chybe alebo zrušení sa pošle POST. Body je JSON.
Hlavičky callback požiadavky
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0Body callback požiadavky
{
"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
}
}Váš server musí vrátiť HTTP 2xx. Pri non-2xx alebo timeoute (10 sek) systém skúsi 5x s exponenciálnym backoffom.
Kódy chýb
Všetky chyby používajú formát: {"code": kód, "message": "identifikátor", "data": {}}
| Kód chyby | message | Popis |
|---|---|---|
| 20001 | api_key_required | API kľúč chýba |
| 20001 | invalid_api_key | Neplatný API kľúč |
| 20001 | ip_not_allowed | IP nie je na whiteliste |
| 20001 | permission_denied | Prístup zamietnutý |
| 30001 | tool_not_found | Nástroj nenájdený |
| 30001 | task_not_found | Úloha nenájdená |
| 30001 | insufficient_coins | Nedostatok mincí |
| 30001 | task_submit_failed | Odoslanie úlohy zlyhalo |
| 30001 | task_query_failed | Dotaz na úlohu zlyhal |
| 30001 | task_already_exists | Úloha už existuje (idempotencia) |
| 40001 | tool_id_required | Parameter tool_id chýba |
| 40001 | param_error | Chyba parametrov |
| 40001 | webhook_url_invalid | Neplatný formát webhook_url |
| 40001 | params_must_be_json_object_or_array | params musí byť JSON objekt alebo pole |
| 40001 | execution_options_must_be_json_object_or_array | execution_options musí byť JSON objekt alebo pole |
Rozsahy kódov chýb
| Rozsah | Kategória |
|---|---|
| 1xxxx | Systémová chyba |
| 2xxxx | Chyba autentifikácie |
| 3xxxx | Chyba obchodnej logiky |
| 4xxxx | Chyba parametrov |
| 5xxxx | Chyba externej závislosti |