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.

Тіло запиту

Вхідні параметри

Кожен запит створює одне завдання. Інструменти генерації тексту в зображення та зображення в зображення повертають одне зображення; розбивка на шари (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. Для всіх інших параметрів діють ті самі правила.

Замініть адреси медіафайлів 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 завдання.

Ваша кінцева точка зворотного виклику (callback 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"
}'

Для зворотних викликів (callbacks) використовується структура відповіді на запит статусу завдання. Сповіщення про збій із поверненням коштів також містять параметр верхнього рівня credits_refunded. Використовуйте id для ідентифікації завдання та status, щоб відрізнити успішно завершені завдання від тих, що зазнали збою. Сповіщення можуть дублюватися: обробляйте їх ідемпотентно за id та status. Зворотні виклики не підписуються цифровим підписом — перевіряйте статус завдання за допомогою автентифікованого запиту до кінцевої точки (endpoint). Помилка доставки сповіщення не скасовує оплату за успішно виконане завдання.

Завдання виконано: дані успішного зворотного виклику

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
}

Приклад обробника

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 та безпосередньо обробляє успішно виконані й невдалі завдання. Додайте у свій додаток збереження даних та дедуплікацію за 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."
  }
}