API документация
Программный интерфейс для асинхронной генерации видео и изображений через единый endpoint. Запрос отправляет задачу в обработку, ответ приходит через polling или webhook.
Базовый URL
Все запросы выполняются по протоколу HTTPS с JSON в теле запросов и ответов.
Аутентификация
Все эндпоинты требуют аутентификации по схеме Bearer Token. Передавайте ваш API-ключ в заголовке Authorization. Получить ключ можно в консоли.
Authorization: Bearer a1b23456-78ce-9123-d45e-bbbbb6b43210
Endpoints
Generate · запуск задачи
Создаёт асинхронную задачу генерации. Сервер сразу возвращает task_id со статусом 202 Accepted. Используйте его для получения результата через /tasks/{task_id} или подпишитесь на webhook.
| Поле | Тип | Описание |
|---|---|---|
| params* | object | Параметры конкретной модели. Поле model_name внутри params задаёт, какая модель будет использована и какие поля доступны. |
| params.model_name* | string | ID модели — например, kling-v3, veo-3-fast, nano-banana. Полный список — на странице Все модели. |
| params.prompt* | string | Текстовое описание генерации. Длина и язык зависят от модели. |
| params.webhook_url | string? | URL, на который придёт POST с результатом, когда задача завершится. |
| params.image_url | string? | URL или Base64 входного изображения для image-to-video / редактирования. |
| params.image_urls | string[]? | Список URL (до 3–4, зависит от модели) для multi-image input. |
| params.aspect_ratio | string? | Соотношение сторон: 16:9, 9:16, 1:1 и т.д. Допустимые значения зависят от модели. |
| params.duration | integer? | Длительность видео в секундах (для моделей, поддерживающих параметр). |
| params.seed | integer? | Сид для воспроизводимости результата. |
curl https://nexusapi.dev/generate \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"params": {
"model_name": "kling-v3",
"prompt": "Дрон над горным озером на рассвете",
"duration": 5,
"aspect_ratio": "16:9"
}
}'import requests, time
API = "https://nexusapi.dev"
KEY = "<YOUR_API_KEY>"
H = {"Authorization": f"Bearer {KEY}"}
# 1. Запускаем задачу
res = requests.post(
f"{API}/generate",
headers=H,
json={
"params": {
"model_name": "veo-3-fast",
"prompt": "a corgi dog running on a beach",
"translate": True,
}
},
)
task_id = res.json()["task_id"]
# 2. Опрашиваем статус
while True:
r = requests.get(f"{API}/tasks/{task_id}", headers=H).json()
if r["status"] in ("completed", "failed"):
print(r)
break
time.sleep(3)const API = "https://nexusapi.dev";
const KEY = process.env.NEXUS_API_KEY;
const H = {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
};
// 1. Запускаем задачу генерации картинки
const start = await fetch(`${API}/generate`, {
method: "POST",
headers: H,
body: JSON.stringify({
params: {
model_name: "nano-banana",
prompt: "combine photos",
image_urls: [
"https://example.com/banana.png",
"https://example.com/apple.png",
],
},
}),
});
const { task_id } = await start.json();
// 2. Опрашиваем статус
while (true) {
const r = await fetch(`${API}/tasks/${task_id}`, { headers: H });
const data = await r.json();
if (data.status === "completed" || data.status === "failed") {
console.log(data);
break;
}
await new Promise((r) => setTimeout(r, 3000));
}{
"message": "Task accepted for processing",
"task_id": "8a3f1c9e-4b62-4a17-9c4d-2e0f8b1c7d20"
}Get Task Status · получение результата
Возвращает текущий статус задачи. Когда status переходит в completed, поле result содержит URL сгенерированного видео или изображения.
| Поле | Тип | Описание |
|---|---|---|
| task_id* | string (uuid) | ID задачи, полученный из ответа POST /generate. |
| Поле | Тип | Описание |
|---|---|---|
| task_id* | string | ID задачи. |
| status* | enum | queued · pending · processing · completed · failed |
| result | object | null | Результат генерации (video_url / image_url и метаданные). Доступен только при status = completed. |
| error | string | null | Сообщение об ошибке при status = failed. |
| created_at | string (datetime) | Время создания задачи. |
curl https://nexusapi.dev/tasks/<TASK_ID> \ -H "Authorization: Bearer <YOUR_API_KEY>"
{
"task_id": "8a3f1c9e-4b62-4a17-9c4d-2e0f8b1c7d20",
"status": "completed",
"result": {
"video_url": "https://cdn.nexusapi.dev/v/8a3f1c9e.mp4",
"duration": 5
},
"error": null,
"created_at": "2026-05-26T13:42:11Z"
}Webhooks
Чтобы не опрашивать /tasks/{task_id} вручную, передайте webhook_url внутри params. Когда задача завершится, мы выполним POST на этот URL с тем же телом, что возвращает GET-эндпоинт статуса.
{
"params": {
"model_name": "kling-v3",
"prompt": "...",
"webhook_url": "https://your-app.example.com/nexus/callback"
}
}Webhook отправляется один раз. Если ваш endpoint вернул ошибку, задача всё равно доступна через polling — повторов из webhook не будет.
Жизненный цикл задачи
- 01queued · Задача принята и поставлена в очередь к нужному провайдеру.
- 02pending · Ждём свободного слота у провайдера.
- 03processing · Модель генерирует контент.
- 04completed · Готово. result содержит URL или base64 результата.
- 05failed · Произошла ошибка. error содержит человекочитаемое сообщение.
Ошибки
| Поле | Тип | Описание |
|---|---|---|
| 202 | Accepted | Задача успешно создана. В теле ответа task_id. |
| 401 | Unauthorized | Не передан Authorization или ключ неверный/отозван. |
| 402 | Payment Required | Недостаточно средств на счёте. Пополните баланс через Telegram-бота. |
| 422 | Validation Error | Тело запроса не прошло валидацию. Проверьте params для выбранной модели. |
| 429 | Too Many Requests | Превышен rate limit. Сделайте паузу и повторите запрос. |
| 5xx | Server Error | Внутренняя ошибка или ошибка провайдера. Безопасно ретраить с экспонентой. |
Schemas
У каждой модели свой набор параметров внутри params: общие поля prompt, model_name, webhook_url и модель-специфичные — duration, aspect_ratio, cfg_scale, negative_prompt, image_url, image_urls, seed и т.д.
Полное описание полей каждой схемы доступно в OpenAPI-спецификации.
