Documentazione API NSFW & Undress AI

Autenticazione

Tutte le richieste API devono includere l'header Authorization.

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

Ottieni la chiave API dalla pagina "Chiavi API" della console. Una chiave per account. Per reimpostarla, usa la console; la vecchia viene invalidata immediatamente.

Crea attività

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

Invia un'attività IA al cluster GPU. Le attività sono asincrone e restituiscono un ID. Ottieni i risultati via API di query o Webhook.

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
tool_id	int	Sì	ID strumento, dalla lista strumenti
params	object	Sì	Parametri attività, oggetto JSON, campi dipendenti dallo strumento
webhook_url	string	No	URL di callback per notifica di completamento
priority	int	No	Priorità attività 1-10, default 5
idempotency_key	string	No	Chiave di idempotenza, previene duplicati
execution_options	object	No	Opzioni di esecuzione, oggetto JSON

Esempio di richiesta

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"
  }'

Esempio di risposta

{
  "code": 0,
  "message": "success",
  "data": {
    "task": {
      "id": 123,
      "status": 0,
      "consume_coins": 5
    },
    "message": "task_submitted"
  }
}

Il saldo viene verificato prima della chiamata. Saldo insufficiente = errore insufficient_coins. Le coin vengono scalate al successo della sottomissione.

Consulta dettaglio attività

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

Consulta dettagli e stato per ID. Durante l'elaborazione, lo stato più recente viene recuperato dal cluster GPU. Query ripetute entro 10 secondi restituiscono cache del DB senza richieste remote.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
id	int	Sì	ID attività

Esempio di risposta

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

Valori di stato attività

status	Significato
0	In elaborazione
1	Completato
-1	Annullato
-2	Fallito

Lista attività

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

Query paginata delle attività dell'account corrente, con filtri per strumento, stato e intervallo di date.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
page	int	No	Numero pagina, default 1
page_size	int	No	Dimensione pagina, default 20, max 50
tool_id	int	No	Filtra per strumento
status	int	No	Filtra per stato (0/1/-1/-2)
days	int	No	Intervallo in giorni, default 30

Esempio di risposta

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

Descrizione campi task_output_json

Campo	Tipo	Descrizione
type	string	Tipo risultato: image o video
url	string	URL CDN del file risultato
file_name	string	Nome file
file_size	int	Dimensione file (byte)
mime_type	string	Tipo MIME, es: image/png, video/mp4
width	int	Larghezza (pixel)
height	int	Altezza (pixel)

Saldo account

GET https://nsfwrouter.xyz/api/v1/account/balance

Consulta saldo coin, ricarica totale e consumo totale dell'account.

Esempio di risposta

{
  "code": 0,
  "message": "success",
  "data": {
    "remain_coins": 5000,
    "total_coins": 10000,
    "used_coins": 5000
  }
}

Callback Webhook

Se webhook_url viene fornito, al completamento, fallimento o annullamento viene inviato un POST a quell'URL. Il body è JSON.

Header della richiesta callback

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

Body della richiesta 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
  }
}

Il tuo server deve rispondere con HTTP 2xx. In caso di risposta non-2xx o timeout (10 sec), il sistema ritenta fino a 5 volte con backoff esponenziale (60s → 120s → 240s → 480s → 960s).

Codici di errore

Tutte le risposte di errore usano un formato unificato: {"code": codice, "message": "identificatore", "data": {}}

Codice errore	message	Descrizione
20001	api_key_required	Chiave API non fornita
20001	invalid_api_key	Chiave API non valida
20001	ip_not_allowed	IP non in whitelist
20001	permission_denied	Permesso negato
30001	tool_not_found	Strumento non trovato
30001	task_not_found	Attività non trovata
30001	insufficient_coins	Saldo coin insufficiente
30001	task_submit_failed	Sottomissione attività fallita
30001	task_query_failed	Query attività fallita
30001	task_already_exists	Attività già esistente (idempotenza)
40001	tool_id_required	Parametro tool_id mancante
40001	param_error	Errore di parametro
40001	webhook_url_invalid	Formato webhook_url non valido
40001	params_must_be_json_object_or_array	params deve essere un oggetto o array JSON
40001	execution_options_must_be_json_object_or_array	execution_options deve essere un oggetto o array JSON

Range codici di errore

Range	Categoria
1xxxx	Errore di sistema
2xxxx	Errore di autenticazione
3xxxx	Errore di logica di business
4xxxx	Errore di parametro
5xxxx	Errore di dipendenza esterna