API-dokumentaatio
Kutsu kaikkia tekoälyominaisuuksia API-avaimellasi, maksa käytön mukaan, integroi muutamalla koodirivillä.
Autentikointi
Kaikissa API-pyynnöissä on oltava header Authorization.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxHae API-avaimesi "API-avaimet" sivulta konsolissa. Yksi avain per tili. Nollaa konsolissa; vanha mitätöidään välittömästi.
Luo tehtävä
https://nsfwrouter.xyz/api/v1/tasks/create
Lähetä tekoälytehtävä GPU-klusterille. Tehtävät ovat asynkronisia ja palauttavat ID:n. Saa tulokset kysely-API:n tai Webhookin kautta.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| tool_id | int | Kyllä | Työkalu-ID, työkaluluettelosta |
| params | object | Kyllä | Tehtävän parametrit, JSON-objekti, kentät riippuvat työkalusta |
| webhook_url | string | Ei | Callback-URL valmistumisilmoitusta varten |
| priority | int | Ei | Tehtävän prioriteetti 1-10, oletus 5 |
| idempotency_key | string | Ei | Idempotency-avain, estää kaksoiskappaleet |
| execution_options | object | Ei | Suoritusvaihtoehdot, JSON-objekti |
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"
}
}Saldo tarkistetaan ennen kutsua. Riittämätön saldo = virhe insufficient_coins. Kolikot vähennetään onnistuneesta lähetyksestä.
Kysy tehtävän tiedot
https://nsfwrouter.xyz/api/v1/tasks/query
Kysy tiedot ja status ID:llä. Käsittelyn aikana uusin status haetaan GPU-klusterilta. Toistuvat kyselyt 10 sekunnin sisällä palauttavat DB-välimuistin ilman etäkyselyitä.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| id | int | Kyllä | Tehtävä-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 | Merkitys |
|---|---|
| 0 | Käsitellään |
| 1 | Valmis |
| -1 | Peruttu |
| -2 | Epäonnistui |
Tehtäväluettelo
https://nsfwrouter.xyz/api/v1/tasks
Sivutettu kysely nykyisen tilin tehtävistä, suodattimilla työkalun, statuksen ja jakson mukaan.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| page | int | Ei | Sivunumero, oletus 1 |
| page_size | int | Ei | Sivun koko, oletus 20, max 50 |
| tool_id | int | Ei | Suodata työkalun mukaan |
| status | int | Ei | Suodata statuksen mukaan (0/1/-1/-2) |
| days | int | Ei | Aikaväli päivissä, oletus 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
}
}| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| type | string | Tulostyyppi: image tai video |
| url | string | CDN-URL tulostiedostolle |
| file_name | string | Tiedostonimi |
| file_size | int | Tiedostokoko (tavua) |
| mime_type | string | MIME-tyyppi, esim. image/png, video/mp4 |
| width | int | Leveys (pikseliä) |
| height | int | Korkeus (pikseliä) |
Tilin saldo
https://nsfwrouter.xyz/api/v1/account/balance
Tarkista kolikko-saldo, kokonaislataus ja kokonaiskulutus nykyiselle tilille.
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhook-callback
Jos webhook_url annetaan, POST lähetetään kyseiseen URL:ään kun tehtävä valmistuu, epäonnistuu tai perutaan. Body on 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
}
}Palvelimesi on palautettava HTTP 2xx. Non-2xx tai timeout (10 sek) sattuessa järjestelmä yrittää uudelleen enintään 5 kertaa eksponentiaalisella backoffilla (60s → 120s → 240s → 480s → 960s).
Virhekoodit
Kaikki virhevastaukset käyttävät yhtenäistä muotoa: {"code": virhekoodi, "message": "tunniste", "data": {}}
| Virhekoodi | message | Kuvaus |
|---|---|---|
| 20001 | api_key_required | API-avainta ei annettu |
| 20001 | invalid_api_key | Virheellinen API-avain |
| 20001 | ip_not_allowed | IP ei whitelistilla |
| 20001 | permission_denied | Pääsy evätty |
| 30001 | tool_not_found | Työkalua ei löydy |
| 30001 | task_not_found | Tehtävää ei löydy |
| 30001 | insufficient_coins | Riittämätön kolikko-saldo |
| 30001 | task_submit_failed | Tehtävän lähetys epäonnistui |
| 30001 | task_query_failed | Tehtävän kysely epäonnistui |
| 30001 | task_already_exists | Tehtävä on jo olemassa (idempotenssi) |
| 40001 | tool_id_required | Parametri tool_id puuttuu |
| 40001 | param_error | Parametrivirhe |
| 40001 | webhook_url_invalid | Virheellinen webhook_url-muoto |
| 40001 | params_must_be_json_object_or_array | params on oltava JSON-objekti tai taulukko |
| 40001 | execution_options_must_be_json_object_or_array | execution_options on oltava JSON-objekti tai taulukko |
| Alue | Kategoria |
|---|---|
| 1xxxx | Järjestelmävirhe |
| 2xxxx | Autentikointivirhe |
| 3xxxx | Liiketoimintalogiikkavirhe |
| 4xxxx | Parametrivirhe |
| 5xxxx | Ulkoinen riippuvuusvirhe |