API-Doku
Rufe alle KI-Funktionen via API-Schlüssel auf, nutzungsabhängig, integriere in wenigen Codezeilen.
Authentifizierung
Alle API-Anfragen müssen den Header Authorization enthalten.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxAPI-Schlüssel in der Konsole unter „API-Schlüssel" abrufen. Ein Schlüssel pro Konto. Zurücksetzen in der Konsole; der alte wird sofort ungültig.
Aufgabe erstellen
https://nsfwrouter.xyz/api/v1/tasks/create
Sende eine KI-Aufgabe an den GPU-Cluster. Aufgaben sind asynchron und geben eine ID zurück. Ergebnisse via Abfrage-API oder Webhook.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| tool_id | int | Ja | Tool-ID, aus der Tool-Liste |
| params | object | Ja | Aufgabenparameter, JSON-Objekt, Felder toolabhängig |
| webhook_url | string | Nein | Callback-URL für Abschlussbenachrichtigung |
| priority | int | Nein | Aufgabenpriorität 1-10, Standard 5 |
| idempotency_key | string | Nein | Idempotenz-Key, verhindert Doppelsubmission |
| execution_options | object | Nein | Ausführungsoptionen, JSON-Objekt |
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"
}
}Vor Aufruf wird das Guthaben geprüft. Bei unzureichendem Guthaben: insufficient_coins. Coins werden bei erfolgreicher Submission sofort abgezogen.
Aufgabendetails abfragen
https://nsfwrouter.xyz/api/v1/tasks/query
Details und Status per ID abfragen. Während der Verarbeitung wird der neueste Status vom GPU-Cluster geholt. Wiederholte Abfragen innerhalb 10 Sekunden liefern gecachte DB-Ergebnisse ohne Remote-Anfragen.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| id | int | Ja | Aufgaben-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 | Bedeutung |
|---|---|
| 0 | In Verarbeitung |
| 1 | Abgeschlossen |
| -1 | Abgebrochen |
| -2 | Fehlgeschlagen |
Aufgabenliste
https://nsfwrouter.xyz/api/v1/tasks
Paginierte Abfrage der Aufgaben des aktuellen Kontos, mit Filterung nach Tool, Status und Zeitraum.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| page | int | Nein | Seitennummer, Standard 1 |
| page_size | int | Nein | Seitengröße, Standard 20, max 50 |
| tool_id | int | Nein | Nach Tool filtern |
| status | int | Nein | Nach Status filtern (0/1/-1/-2) |
| days | int | Nein | Abfragezeitraum in Tagen, Standard 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
}
}| Feld | Typ | Beschreibung |
|---|---|---|
| type | string | Ergebnistyp: image oder video |
| url | string | CDN-URL der Ergebnisdatei |
| file_name | string | Dateiname |
| file_size | int | Dateigröße (Bytes) |
| mime_type | string | MIME-Typ, z.B. image/png, video/mp4 |
| width | int | Breite (Pixel) |
| height | int | Höhe (Pixel) |
Kontoguthaben
https://nsfwrouter.xyz/api/v1/account/balance
Aktuelles Coin-Guthaben, Gesamt-Aufladung und Gesamt-Verbrauch abfragen.
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook-Callback
Wenn webhook_url angegeben wird, sendet das System bei Abschluss, Fehlschlag oder Abbruch ein POST an diese URL. Body ist 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
}
}Dein Server muss HTTP 2xx zurückgeben. Bei non-2xx oder Timeout (10 Sek.) automatischer Retry bis zu 5× mit exponentiellem Backoff (60s → 120s → 240s → 480s → 960s).
Fehlercodes
Alle Fehlerantworten verwenden ein einheitliches Format: {"code": fehlercode, "message": "identifikator", "data": {}}
| Fehlercode | message | Beschreibung |
|---|---|---|
| 20001 | api_key_required | API-Schlüssel nicht angegeben |
| 20001 | invalid_api_key | Ungültiger API-Schlüssel |
| 20001 | ip_not_allowed | IP nicht in Whitelist |
| 20001 | permission_denied | Zugriff verweigert |
| 30001 | tool_not_found | Tool nicht gefunden |
| 30001 | task_not_found | Aufgabe nicht gefunden |
| 30001 | insufficient_coins | Coin-Guthaben unzureichend |
| 30001 | task_submit_failed | Aufgaben-Submission fehlgeschlagen |
| 30001 | task_query_failed | Aufgabenabfrage fehlgeschlagen |
| 30001 | task_already_exists | Aufgabe existiert bereits (Idempotenz) |
| 40001 | tool_id_required | Parameter tool_id fehlt |
| 40001 | param_error | Parameterfehler |
| 40001 | webhook_url_invalid | webhook_url Format ungültig |
| 40001 | params_must_be_json_object_or_array | params muss ein JSON-Objekt oder Array sein |
| 40001 | execution_options_must_be_json_object_or_array | execution_options muss ein JSON-Objekt oder Array sein |
| Bereich | Kategorie |
|---|---|
| 1xxxx | Systemfehler |
| 2xxxx | Authentifizierungsfehler |
| 3xxxx | Geschäftslogikfehler |
| 4xxxx | Parameterfehler |
| 5xxxx | Externe Abhängigkeitsfehler |