NSFW & 脱衣 AI 生成 API 文档

认证方式

所有 API 请求需在请求 Header 中携带 Authorization 请求头。

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

API Key 在控制台「API Keys」页面获取，一个账户对应一个 Key。如需重置，可在控制台操作，重置后旧 Key 立即失效。

创建任务

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	外部依赖错误