API dokumentacija
API dokumentacija
Pozivajte sve AI značajke putem API ključa, plaćanje po korištenju, integracija u nekoliko redaka.
Autentikacija
Svi API zahtjevi moraju sadržavati zaglavlje Authorization.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxDobijte API ključ na stranici „API ključevi" u konzoli. Jedan ključ po računu. Reset u konzoli; stari se odmah poništava.
Stvaranje zadatka
POST
https://nsfwrouter.xyz/api/v1/tasks/create
Pošaljite AI zadatak u GPU klaster. Zadaci su asinkroni, vraćaju ID. Rezultati putem API ili Webhooka.
Parametri zahtjeva
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
| tool_id | int | Da | ID alata, s popisa alata |
| params | object | Da | Parametri zadatka, JSON objekt, polja ovise o alatu |
| webhook_url | string | Ne | URL callback za obavijest o završetku |
| priority | int | Ne | Prioritet zadatka 1-10, zadano 5 |
| idempotency_key | string | Ne | Ključ idempotencije, sprječava duplikate |
| execution_options | object | Ne | Opcije izvršavanja, JSON objekt |
Primjer zahtjeva
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"
}'Primjer odgovora
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}Saldo se provjerava prije poziva. Nedovoljno = pogreška insufficient_coins. Novčići se odbiju pri uspješnom slanju.
Upit zadatka
GET
https://nsfwrouter.xyz/api/v1/tasks/query
Upit detalja i statusa po ID. Tijekom obrade, status se uzima s GPU klastera. Ponovljeni upiti u 10 sek vraćaju DB cache.
Parametri upita
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
| id | int | Da | ID zadatka |
Primjer odgovora
{
"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
}
}
}Vrijednosti statusa zadatka
| status | Značenje |
|---|---|
| 0 | Obrada |
| 1 | Završeno |
| -1 | Otkazano |
| -2 | Neuspjelo |
Popis zadataka
GET
https://nsfwrouter.xyz/api/v1/tasks
Stranični upit zadataka računa, s filtrima na alat, status i razdoblje.
Parametri upita
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
| page | int | Ne | Broj stranice, zadano 1 |
| page_size | int | Ne | Veličina stranice, zadano 20, max 50 |
| tool_id | int | Ne | Filtriraj po alatu |
| status | int | Ne | Filtriraj po statusu (0/1/-1/-2) |
| days | int | Ne | Razdoblje u danima, zadano 30 |
Primjer odgovora
{
"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
}
}Opis polja task_output_json
| Polje | Tip | Opis |
|---|---|---|
| type | string | Tip rezultata: image ili video |
| url | string | CDN URL za datoteku rezultata |
| file_name | string | Naziv datoteke |
| file_size | int | Veličina (bajtovi) |
| mime_type | string | MIME tip, npr. image/png, video/mp4 |
| width | int | Širina (pikseli) |
| height | int | Visina (pikseli) |
Saldo računa
GET
https://nsfwrouter.xyz/api/v1/account/balance
Provjerite saldo novčića, ukupnu uplatu i ukupnu potrošnju.
Primjer odgovora
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook callback
Ako je naveden webhook_url, šalje se POST pri završetku, neuspjehu ili otkazivanju. Body je JSON.
Zaglavlja callback zahtjeva
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0Body callback zahtjeva
{
"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
}
}Vaš server mora vratiti HTTP 2xx. Pri non-2xx ili timeoutu (10 sek), sustav pokušava do 5 puta s eksponencijalnim backoffom.
Kodovi pogrešaka
Svi odgovori na pogreške koriste format: {"code": kod, "message": "identifikator", "data": {}}
| Kod pogreške | message | Opis |
|---|---|---|
| 20001 | api_key_required | API ključ nije naveden |
| 20001 | invalid_api_key | Nevažeći API ključ |
| 20001 | ip_not_allowed | IP nije na whitelisti |
| 20001 | permission_denied | Pristup odbijen |
| 30001 | tool_not_found | Alat nije pronađen |
| 30001 | task_not_found | Zadatak nije pronađen |
| 30001 | insufficient_coins | Nedovoljno novčića |
| 30001 | task_submit_failed | Slanje zadatka neuspjelo |
| 30001 | task_query_failed | Upit zadatka neuspio |
| 30001 | task_already_exists | Zadatak već postoji (idempotencija) |
| 40001 | tool_id_required | Parametar tool_id nedostaje |
| 40001 | param_error | Pogreška parametara |
| 40001 | webhook_url_invalid | Nevažeći format webhook_url |
| 40001 | params_must_be_json_object_or_array | params mora biti JSON objekt ili polje |
| 40001 | execution_options_must_be_json_object_or_array | execution_options mora biti JSON objekt ili polje |
Rasponi kodova pogrešaka
| Raspon | Kategorija |
|---|---|
| 1xxxx | Sistemska pogreška |
| 2xxxx | Pogreška autentikacije |
| 3xxxx | Pogreška poslovne logike |
| 4xxxx | Pogreška parametara |
| 5xxxx | Pogreška vanjske ovisnosti |