مستندات API NSFW و Undress AI

احراز هویت

همه درخواست‌های API باید شامل هدر Authorization باشند.

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

کلید API را از صفحه «کلیدهای API» در کنسول بگیرید. یک کلید به ازای هر حساب. بازنشانی در کنسول؛ قدیمی فوراً باطل می‌شود.

ساخت وظیفه

POST https://nsfwrouter.xyz/api/v1/tasks/create

وظیفه AI به خوشه GPU بفرستید. وظایف ناهمگام، ID برمی‌گردانند. نتایج از طریق API یا Webhook.

پارامترهای درخواست

پارامتر	نوع	الزامی	توضیح
tool_id	int	بله	شناسه ابزار، از فهرست ابزارها
params	object	بله	پارامترهای وظیفه، JSON object، فیلدها بسته به ابزار
webhook_url	string	خیر	URL callback برای اعلان تکمیل
priority	int	خیر	اولویت وظیفه 1-10، پیش‌فرض 5
idempotency_key	string	خیر	کلید idempotency، از تکرار جلوگیری می‌کند
execution_options	object	خیر	گزینه‌های اجرا، 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"
  }
}

موجودی قبل از فراخوانی بررسی می‌شود. ناکافی = خطای insufficient_coins. سکه‌ها در ارسال موفق کسر می‌شوند.

پرس‌وجوی وظیفه

GET https://nsfwrouter.xyz/api/v1/tasks/query

جزئیات و وضعیت را بر اساس ID پرس‌وجو کنید. هنگام پردازش، وضعیت از خوشه GPU گرفته می‌شود. پرس‌وجوی مکرر در ۱۰ ثانیه DB cache برمی‌گرداند.

پارامترهای پرس‌وجو

پارامتر	نوع	الزامی	توضیح
id	int	بله	شناسه وظیفه

نمونه پاسخ

{
  "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

فیلد	نوع	توضیح
type	string	نوع نتیجه: image یا video
url	string	URL 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 callback

اگر webhook_url مشخص شده باشد، POST در تکمیل، شکست یا لغو ارسال می‌شود. Body به JSON.

هدرهای درخواست callback

Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0

body درخواست callback

{
  "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 برگرداند. در non-2xx یا timeout (10 ثانیه)، سیستم تا 5 بار با backoff نمایی تلاش مجدد می‌کند.

کدهای خطا

همه پاسخ‌های خطا از فرمت یکسان استفاده می‌کنند: {"code": کد, "message": "identifier", "data": {}}

کد خطا	message	توضیح
20001	api_key_required	کلید API ارائه نشده
20001	invalid_api_key	کلید API نامعتبر
20001	ip_not_allowed	IP در whitelist نیست
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	وظیفه از قبل وجود دارد (idempotency)
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 object یا array باشد
40001	execution_options_must_be_json_object_or_array	execution_options باید JSON object یا array باشد

بازه‌های کدهای خطا

بازه	دسته
1xxxx	خطای سیستم
2xxxx	خطای احراز هویت
3xxxx	خطای منطق کسب‌وکار
4xxxx	خطای پارامتر
5xxxx	خطای وابستگی خارجی