API Docs
Call all AI capabilities via API Key, pay-as-you-go, integrate with just a few lines of code.
Authentication
All API requests must include an Authorization header.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxGet your API Key from the Console "API Keys" page. One key per account. To reset, use the console; the old key is immediately invalidated after reset.
Create Task
https://nsfwrouter.xyz/api/v1/tasks/create
Submit an AI task to the GPU cluster for execution. Tasks are processed asynchronously, returning a task ID. Get results via the query API or Webhook.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tool_id | int | Yes | Tool ID, obtained from the tools list |
| params | object | Yes | Task parameters, JSON object, fields depend on the tool |
| webhook_url | string | No | Callback URL for task completion notification |
| priority | int | No | Task priority 1-10, default 5 |
| idempotency_key | string | No | Idempotency key, prevents duplicate submissions |
| execution_options | object | No | Execution options, 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"
}
}Account balance is verified before calling. Insufficient balance returns insufficient_coins error. Coins are deducted immediately upon successful task submission.
Query Task Detail
https://nsfwrouter.xyz/api/v1/tasks/query
Query task details and status by task ID. When the task is processing, the latest status is fetched from the GPU cluster. Repeated queries within 10 seconds return cached database results without remote requests.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | int | Yes | Task 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 | Meaning |
|---|---|
| 0 | Processing |
| 1 | Completed |
| -1 | Cancelled |
| -2 | Failed |
Task List
https://nsfwrouter.xyz/api/v1/tasks
Paginated query of the current account's task list, supports filtering by tool, status and time range.
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | int | No | Page number, default 1 |
| page_size | int | No | Page size, default 20, max 50 |
| tool_id | int | No | Filter by tool |
| status | int | No | Filter by status (0/1/-1/-2) |
| days | int | No | Query time range in days, default 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
}
}| Field | Type | Description |
|---|---|---|
| type | string | Result type: image or video |
| url | string | Result file CDN URL |
| file_name | string | File name |
| file_size | int | File size (bytes) |
| mime_type | string | MIME type, e.g. image/png, video/mp4 |
| width | int | Width (pixels) |
| height | int | Height (pixels) |
Account Balance
https://nsfwrouter.xyz/api/v1/account/balance
Query the current account's coin balance, total recharge and total consumption.
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook Callback
If webhook_url is provided when creating a task, a POST request is sent to that URL when the task completes, fails or is cancelled. The request body is JSON format.
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
}
}Your server must return an HTTP 2xx status code to indicate successful receipt. If a non-2xx response or timeout (10 seconds) occurs, the system will automatically retry up to 5 times with exponential backoff (60s → 120s → 240s → 480s → 960s).
Error Codes
All error responses use a unified format: {"code": error_code, "message": "error_identifier", "data": {}}
| Error Code | message | Description |
|---|---|---|
| 20001 | api_key_required | API Key not provided |
| 20001 | invalid_api_key | Invalid API Key |
| 20001 | ip_not_allowed | IP not in whitelist |
| 20001 | permission_denied | Permission denied |
| 30001 | tool_not_found | Tool not found |
| 30001 | task_not_found | Task not found |
| 30001 | insufficient_coins | Insufficient coin balance |
| 30001 | task_submit_failed | Task submission failed |
| 30001 | task_query_failed | Task query failed |
| 30001 | task_already_exists | Task already exists (idempotency hit) |
| 40001 | tool_id_required | Missing tool_id parameter |
| 40001 | param_error | Parameter error |
| 40001 | webhook_url_invalid | Invalid webhook_url format |
| 40001 | params_must_be_json_object_or_array | params must be a JSON object or array |
| 40001 | execution_options_must_be_json_object_or_array | execution_options must be a JSON object or array |
| Range | Category |
|---|---|
| 1xxxx | System-level error |
| 2xxxx | Authentication error |
| 3xxxx | Business logic error |
| 4xxxx | Parameter error |
| 5xxxx | External dependency error |