API 文件
API 文件
透過 API Key 呼叫全部 AI 能力，按量計費，幾行程式碼即可接入。
認證方式
所有 API 請求需在請求標頭中攜帶 Authorization 請求標頭。
Authorization: Bearer sk-xxxxxxxxxxxxxxxxAPI Key 在控制台「API 金鑰」頁面取得，一個帳號對應一組金鑰。如需重設，可在控制台操作，重設後舊金鑰立即失效。
建立任務
POST
https://nsfwrouter.xyz/api/v1/tasks/create
提交一個 AI 任務到 GPU 叢集執行。任務為非同步處理，提交後返回任務 ID，透過查詢介面或 Webhook 取得結果。
請求參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| tool_id | int | 是 | 工具 ID，可從工具列表取得 |
| params | object | 是 | 任務參數，JSON 物件，具體欄位取決於工具 |
| webhook_url | string | 否 | 任務完成後回呼通知網址 |
| priority | int | 否 | 任務優先級 1-10，預設 5 |
| idempotency_key | string | 否 | 冪等鍵，防止重複提交 |
| execution_options | object | 否 | 執行選項，JSON 物件 |
請求範例
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"
}
}呼叫前會校驗帳戶餘額，餘額不足返回 insufficient_coins 錯誤。任務提交成功後金幣立即扣除。
查詢任務詳情
GET
https://nsfwrouter.xyz/api/v1/tasks/query
透過任務 ID 查詢任務詳情和狀態。任務處理中時會同步拉取 GPU 叢集最新狀態，10 秒內重複查詢直接返回資料庫結果，不重複請求遠端。
查詢參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | int | 是 | 任務 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 | 含義 |
|---|---|
| 0 | 處理中 |
| 1 | 已完成 |
| -1 | 已取消 |
| -2 | 失敗 |
任務列表
GET
https://nsfwrouter.xyz/api/v1/tasks
分頁查詢當前帳號的任務列表，支援按工具、狀態和時間範圍篩選。
查詢參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| page | int | 否 | 頁碼，預設 1 |
| page_size | int | 否 | 每頁數量，預設 20，最大 50 |
| tool_id | int | 否 | 按工具篩選 |
| status | int | 否 | 按狀態篩選（0/1/-1/-2） |
| days | int | 否 | 查詢天數範圍，預設 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
}
}task_output_json item 欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| type | string | 結果類型：image 或 video |
| url | string | 結果檔案 CDN 網址 |
| file_name | string | 檔案名稱 |
| file_size | int | 檔案大小（位元組） |
| mime_type | string | MIME 類型，如 image/png、video/mp4 |
| width | int | 寬度（像素） |
| height | int | 高度（像素） |
帳戶餘額
GET
https://nsfwrouter.xyz/api/v1/account/balance
查詢當前帳號的金幣餘額、累計儲值和累計消費。
回應範例
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook 回呼
建立任務時若傳入 webhook_url，任務完成、失敗或取消後會向該網址發送 POST 請求，請求體為 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
}
}你的伺服器需回傳 HTTP 2xx 狀態碼表示接收成功。若回傳非 2xx 或逾時（10 秒），系統會自動重試，最多 5 次，採用指數退避策略（60s → 120s → 240s → 480s → 960s）。
錯誤碼
所有錯誤回應統一格式：{"code": 錯誤碼, "message": "錯誤標識", "data": {}}
| 錯誤碼 | message | 說明 |
|---|---|---|
| 20001 | api_key_required | 未提供 API Key |
| 20001 | invalid_api_key | API Key 無效 |
| 20001 | ip_not_allowed | IP 不在白名單內 |
| 20001 | permission_denied | 無權存取該資源 |
| 30001 | tool_not_found | 工具不存在 |
| 30001 | task_not_found | 任務不存在 |
| 30001 | insufficient_coins | 金幣餘額不足 |
| 30001 | task_submit_failed | 任務提交失敗 |
| 30001 | task_query_failed | 任務查詢失敗 |
| 30001 | task_already_exists | 任務已存在（冪等命中） |
| 40001 | tool_id_required | 缺少 tool_id 參數 |
| 40001 | param_error | 參數錯誤 |
| 40001 | webhook_url_invalid | webhook_url 格式不正確 |
| 40001 | params_must_be_json_object_or_array | params 必須是 JSON 物件或陣列 |
| 40001 | execution_options_must_be_json_object_or_array | execution_options 必須是 JSON 物件或陣列 |
錯誤碼範圍
| 範圍 | 分類 |
|---|---|
| 1xxxx | 系統級錯誤 |
| 2xxxx | 鑑權相關 |
| 3xxxx | 業務邏輯錯誤 |
| 4xxxx | 參數錯誤 |
| 5xxxx | 外部依賴錯誤 |