API-documentatie
Roep alle AI-mogelijkheden aan via je API-sleutel, betalen per gebruik, integreer in enkele regels code.
Authenticatie
Alle API-verzoeken moeten de header Authorization bevatten.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxVerkrijg je API-sleutel op de pagina "API-sleutels" in de console. Eén sleutel per account. Reset via de console; de oude wordt direct ongeldig.
Taak aanmaken
https://nsfwrouter.xyz/api/v1/tasks/create
Stuur een AI-taak naar het GPU-cluster. Taken zijn asynchroon en retourneren een ID. Resultaten via query-API of Webhook.
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
| tool_id | int | Ja | Tool-ID, uit de tool-lijst |
| params | object | Ja | Taakparameters, JSON-object, velden afhankelijk van tool |
| webhook_url | string | Nee | Callback-URL voor voltooiingsmelding |
| priority | int | Nee | Taakprioriteit 1-10, standaard 5 |
| idempotency_key | string | Nee | Idempotency-key, voorkomt duplicaten |
| execution_options | object | Nee | Uitvoeringsopties, JSON-object |
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"
}'{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}Saldo wordt gecontroleerd voor aanroep. Onvoldoende saldo = fout insufficient_coins. Coins worden afgeschreven bij succesvolle indiening.
Taakdetail opvragen
https://nsfwrouter.xyz/api/v1/tasks/query
Details en status opvragen per ID. Tijdens verwerking wordt de laatste status uit het GPU-cluster gehaald. Herhaalde queries binnen 10 seconden retourneren DB-cache zonder externe verzoeken.
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
| id | int | Ja | Taak-ID |
{
"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
}
}
}| status | Betekenis |
|---|---|
| 0 | In verwerking |
| 1 | Voltooid |
| -1 | Geannuleerd |
| -2 | Mislukt |
Takenlijst
https://nsfwrouter.xyz/api/v1/tasks
Gepagineerde query van taken van het huidige account, met filters op tool, status en periode.
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
| page | int | Nee | Paginanummer, standaard 1 |
| page_size | int | Nee | Paginagrootte, standaard 20, max 50 |
| tool_id | int | Nee | Filteren op tool |
| status | int | Nee | Filteren op status (0/1/-1/-2) |
| days | int | Nee | Periode in dagen, standaard 30 |
{
"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
}
}| Veld | Type | Beschrijving |
|---|---|---|
| type | string | Resultaattype: image of video |
| url | string | CDN-URL van resultaatbestand |
| file_name | string | Bestandsnaam |
| file_size | int | Bestandsgrootte (bytes) |
| mime_type | string | MIME-type, bijv. image/png, video/mp4 |
| width | int | Breedte (pixels) |
| height | int | Hoogte (pixels) |
Accountsaldo
https://nsfwrouter.xyz/api/v1/account/balance
Bekijk coins-saldo, totale opwaardering en totaal verbruik van het huidige account.
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook-callback
Als webhook_url is opgegeven, wordt bij voltooiing, fout of annulering een POST naar die URL gestuurd. Body is JSON.
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0{
"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
}
}Je server moet HTTP 2xx retourneren. Bij non-2xx of timeout (10 sec) herprobeert het systeem tot 5 keer met exponentiële backoff (60s → 120s → 240s → 480s → 960s).
Foutcodes
Alle foutreacties gebruiken een uniform formaat: {"code": foutcode, "message": "identificatie", "data": {}}
| Foutcode | message | Beschrijving |
|---|---|---|
| 20001 | api_key_required | Geen API-sleutel opgegeven |
| 20001 | invalid_api_key | Ongeldige API-sleutel |
| 20001 | ip_not_allowed | IP niet op whitelist |
| 20001 | permission_denied | Toegang geweigerd |
| 30001 | tool_not_found | Tool niet gevonden |
| 30001 | task_not_found | Taak niet gevonden |
| 30001 | insufficient_coins | Onvoldoende coins |
| 30001 | task_submit_failed | Taakindiening mislukt |
| 30001 | task_query_failed | Taakquery mislukt |
| 30001 | task_already_exists | Taak bestaat al (idempotentie) |
| 40001 | tool_id_required | Parameter tool_id ontbreekt |
| 40001 | param_error | Parameterfout |
| 40001 | webhook_url_invalid | Ongeldig webhook_url formaat |
| 40001 | params_must_be_json_object_or_array | params moet een JSON-object of array zijn |
| 40001 | execution_options_must_be_json_object_or_array | execution_options moet een JSON-object of array zijn |
| Bereik | Categorie |
|---|---|
| 1xxxx | Systeemfout |
| 2xxxx | Authenticatiefout |
| 3xxxx | Bedrijfslogica-fout |
| 4xxxx | Parameterfout |
| 5xxxx | Externe afhankelijkheidsfout |