Seedream 5.0 Flash API

Возможности

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

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

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

Идемпотентность запросов не поддерживается. Каждый корректный запрос 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-flash",
  "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": 2
}

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

Генерируйте изображения, редактируйте референсы или разделяйте изображение на слои с помощью вашего 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-flash",
  "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-flash",
  "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-flash",
  "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": 34
}

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

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-flash",
  "credits": 8,
  "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-flash",
  "credits": 2,
  "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-flash",
  "credits": 2,
  "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-flash",
  "credits": 2,
  "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-flash",
  "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-flash",
  "credits": 2,
  "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-flash",
  "credits": 2,
  "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": 2
}

Пример обработчика (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."
  }
}