Интеграция с API Seevio

Выбор модели

Документация к каждой модели содержит полный список параметров, тарифы и примеры. Интеграцию можно полностью настроить, используя страницу конкретной модели.

Аутентификация

Создайте API-ключ в панели управления. Полный ключ показывается только один раз. Храните его на своём сервере и передавайте в качестве Bearer-токена в заголовке каждого запроса.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Задайте переменную окружения SEEVIO_API_KEY перед запуском этих примеров. Примеры на JavaScript выполняются на стороне сервера с помощью Node.js; примеры на Python используют библиотеку requests.

Быстрый старт

В этом примере генерируется 5-секундное видео 720p с помощью Seedance 2.5. Откройте документацию модели, чтобы посмотреть все режимы генерации и ограничения параметров.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Пример ответа при создании задачи

После того как вышеуказанный запрос будет принят, API вернет этот ответ в формате JSON. Параметр taskId представляет собой идентификатор задачи, используемый для последующих запросов ее статуса; credits — это количество кредитов, зарезервированных для выполнения данной задачи. Этот ответ подтверждает лишь создание задачи, а не готовность видео. Чтобы получить готовый видеофайл, вам необходимо периодически опрашивать статус задачи или использовать Webhook.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

Запрос статуса задачи

Замените ID в примере на taskId, полученный при создании. Запросы возвращают только те задачи, которые принадлежат владельцу API-ключа; недоступные или несуществующие ID возвращают HTTP 404.

Для начала делайте запросы каждые 10–20 секунд, увеличивайте интервал при получении HTTP 429 и прекращайте опрос, когда статус изменится на completed или failed. Для продакшена рекомендуется использовать вебхуки. Каждый пример кода ниже выполняет один запрос.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Успешное выполнение: ответ на запрос с готовым видео

Когда запрос возвращает status=completed, генерация видео завершена. Ссылки на видеофайлы можно получить из data.results — скачайте их до наступления времени, указанного в data.video_expires_at. Значение billing_status=charged означает, что зарезервированные кредиты были списаны.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Ошибка выполнения: ответ на запрос со сведениями об ошибке и оплате

Если запрос возвращает status=failed, генерация завершилась неудачно. Причину ошибки можно узнать в failed_reason, а статус возврата средств — в billing_status. В данном примере значение refunded означает, что кредиты были возвращены на баланс. При этом в credits отображается изначально зарезервированная сумма, а блок data в ответе отсутствует.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Вебхуки

Для интеграции в продакшене укажите callback_url при создании задачи. Документация каждой модели содержит формат полезной нагрузки и пример обработчика вебхуков.

Укажите callback_url в запросе на создание задачи, чтобы получать POST-запросы с JSON-телом при завершении или ошибке задачи. Возвращайте ответ со статусом 2xx в течение 15 секунд. В случае неудачной доставки попытки повторяются; обрабатывайте повторные доставки идемпотентно по ID задачи.

Ваша конечная точка (endpoint) для обратного вызова должна принимать POST-запросы с телом запроса в формате JSON (Content-Type: application/json).

Создание задачи с вебхуком

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Полезная нагрузка вебхука отличается от ответа на запрос статуса задачи: в ней отсутствуют billing_status и credits; детали ошибки находятся в data.failed_reason и data.credits_refunded. Поле created_at в вебхуке указывает время создания события в формате Unix timestamp (в секундах).

Задача выполнена: структура успешного ответа (callback payload)

При успешной генерации вебхук возвращает статус status=completed. Используйте id для идентификации задачи, а массив data.results — для получения URL-адресов видео. Скачайте и сохраните результаты до наступления времени, указанного в data.video_expires_at.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Ошибка выполнения задачи: структура ответа при сбое

Если генерация завершилась ошибкой, вебхук возвращает статус status=failed. Используйте id для идентификации задачи, data.failed_reason — для выяснения причины сбоя, а data.credits_refunded — для проверки количества возвращенных кредитов.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

Пример обработчика (receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

В этом примере для Next.js показано, как считывать JSON-тело вебхука и обрабатывать успешно выполненные и проваленные задачи. Для интеграции в продакшн добавьте сохранение данных в БД и дедупликацию по task-ID, а ресурсоемкие фоновые задачи отправляйте в очередь перед отправкой ответа на вебхук.

Ошибки

Ошибки HTTP возвращают объект error с полями code и message. Успешно принятая задача всё ещё может завершиться ошибкой позже; запрашивайте статус задачи или обрабатывайте вебхук об ошибке.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}