API документация
API документация
Извиквайте всички AI функции чрез API ключ, плащане по използване, интеграция в няколко реда.
Удостоверяване
Всички API заявки трябва да съдържат хедър Authorization.
Authorization: Bearer sk-xxxxxxxxxxxxxxxxВземете API ключ от страницата „API ключове" в конзолата. Един ключ на профил. Нулиране в конзолата; старият веднага се анулира.
Създаване на задача
POST
https://nsfwrouter.xyz/api/v1/tasks/create
Изпратете AI задача към GPU клъстер. Задачите са асинхронни, връщат ID. Резултати чрез API или Webhook.
Параметри на заявка
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| tool_id | int | Да | ID на инструмент, от списъка |
| params | object | Да | Параметри на задача, JSON обект, полетата зависят от инструмента |
| webhook_url | string | Не | URL callback за известие при завършване |
| 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 сек връщат DB cache.
Параметри на запитване
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
| 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
| Поле | Тип | Описание |
|---|---|---|
| type | string | Тип резултат: image или video |
| url | string | CDN URL за файл с резултат |
| 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.0Body на 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": "идентификатор", "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 | Задачата вече съществува (идемпотентност) |
| 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 | Грешка във външна зависимост |