Seedream 5.0 Pro API

Возможности

Тарифы и кредиты

Цены ниже указаны за одно возвращенное изображение. Обычная генерация резервирует стоимость одного изображения. Разделение на слои резервирует стоимость 17 изображений, списывает плату по фактическому количеству возвращенных изображений (включая базовое) и возвращает неиспользованные кредиты на исходный баланс. Задачи с ошибкой полностью компенсируются.

При разрешении по умолчанию 2K разделение на слои резервирует 136 кр. Если возвращено четыре изображения, итоговое списание составит 32 кр., а 104 кр. будут возвращены на баланс.

Идемпотентность запросов не поддерживается. Каждый корректный запрос POST создает новую тарифицируемую задачу. Если результат отправки неизвестен, проверьте статус по возвращенному taskId. Повторная отправка POST может привести к созданию дублирующей задачи.

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

Создайте 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.

Тело запроса

Входные параметры

Каждый запрос создает одну задачу. Генерация текста в изображение (text-to-image) и изображения в изображение (image-to-image) возвращают одно изображение. Послойное разложение (layer-decomposition) возвращает от 1 до 17 изображений, включая базовое. Не передавайте параметр aspect_ratio для layer-decomposition.

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

Отправьте этот минимальный запрос, сохраните полученный taskId, а затем используйте пример запроса статуса ниже. Значение credits в ответе на создание задачи — это зарезервированная сумма.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

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

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

Из текста в изображение

Генерируйте изображения, редактируйте референсы или разделяйте изображение на слои с помощью вашего API-ключа Seevio. Задачи выполняются асинхронно; сохраняйте taskId и опрашивайте эндпоинт задачи либо настройте получение колбэка.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Из изображения в изображение

Для редактирования изображений установите параметр generation_type в значение image-to-image и передайте массив image_urls. Все остальные параметры используют тот же контракт.

Замените демонстрационные медиа-URL example.com своими собственными публично доступными HTTPS-файлами. Примеры URL служат лишь для демонстрации структуры запроса и не являются скачиваемыми ресурсами.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Разделение на слои

Установите generation_type в значение layer-decomposition и укажите ровно один URL-адрес изображения. Параметр aspect_ratio указывать не нужно. Параметр output_format влияет только на формат базового изображения. Разделенные слои всегда возвращаются в формате PNG с сохранением прозрачности. Сохраните каждый URL-адрес, возвращённый в data.results.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

Разделение на слои может возвращать несколько URL изображений в массиве data.results: базовое изображение и разделенные слои. Каждый URL указывает на отдельное изображение. Количество результатов зависит от задачи (всего от 1 до 17 изображений); обрабатывайте весь массив целиком, а не только элемент data.results[0]. Этот массив содержится как в ответе на запрос статуса выполненной задачи, так и в вебхуке об успешном завершении. Первоначальный ответ на запрос создания содержит только taskId и зарезервированные кредиты, но не URL изображений.

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

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

Выполнено разделение на слои: несколько URL изображений

В данном примере ответа показаны четыре готовых изображения: одно базовое изображение и три слоя. Ваша задача может вернуть другое количество. При запрошенном разрешении 2K значение credits является окончательной стоимостью за все четыре изображения; неиспользованная часть первоначального резерва на 17 изображений была возвращена на баланс.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Обработка каждого возвращенного изображения

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

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

Замените 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"

В очереди

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Завершено

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Ошибка

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Ссылки на результаты доступны в течение 30 дней после сохранения. По истечении этого срока массив results будет пуст.

Вебхуки

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

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

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

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Вебхуки используют структуру ответа для запроса задачи. Уведомления о сбоях с возвратом средств также содержат поле credits_refunded на верхнем уровне. Используйте id для идентификации задачи и status для определения её успешного завершения или сбоя. Уведомления могут приходить повторно: обрабатывайте их идемпотентно по id и status. Вебхуки не имеют цифровой подписи; проверяйте статус задачи через аутентифицированную конечную точку запроса. Сбой доставки уведомления не приводит к возврату средств за успешно выполненную задачу.

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

created_at — время создания события, task_created_at — время создания задачи, в секундах Unix. Примеры показывают рекомендуемые поля; ответ может содержать дополнительные поля.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

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

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

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

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // 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."
  }
}

Ошибки содержат коды error.code и сообщения error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Ошибка 402 insufficient_credits означает, что на вашем балансе недостаточно кредитов для выполнения этого запроса.

Лимиты запросов

Создание задач: по умолчанию для каждого API-ключа разрешено до 100 запросов в минуту. Индивидуальные лимиты запросов на данный момент не поддерживаются.

Получение информации о задачах: по умолчанию для каждого API-ключа разрешено до 120 запросов в минуту. Запросы на получение информации и запросы на создание задач учитываются раздельно.

Запросы на создание изображений и видео используют общий лимит частоты запросов для одного API-ключа.

HTTP 429 возвращает заголовок Retry-After: 60 для создания задач и Retry-After: 5 для запросов статуса. Используйте экспоненциальную задержку и избегайте избыточного опроса.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}