API Kling 4.0 уже доступен. Попробуйте генерацию видео →
PoYoPoYo
tutorials

Руководство по API Seedream 5.0 Pro: генерация и редактирование изображений с помощью кода

Poyo.ai Team
5 min read
Share:

Руководство по API Seedream 5.0 Pro

API Seedream 5.0 Pro предоставляет разработчикам доступ к флагманской модели генерации и редактирования изображений ByteDance через асинхронный рабочий процесс, ориентированный на использование в продакшене. В этом руководстве показано, как отправлять задачи преобразования текста в изображение и редактирования изображений через Poyo.ai, а затем получать результаты с помощью опроса статуса или вебхука.

Текущая цена составляет 15 кредитов, примерно $0.075 за одно сгенерированное изображение, для обоих вариантов модели.

Модели API и параметры

Рабочий процессID модели
Текст в изображениеseedream-5.0-pro
Редактирование изображенийseedream-5.0-pro-edit

Поддерживаемые входные параметры:

  • prompt: обязательная инструкция для генерации или редактирования
  • size: пресет разрешения, например 1K или 2K, либо соотношение сторон, например 1:1, 4:3, 3:4, 16:9 или 9:16
  • n: количество генерируемых изображений
  • output_format: jpeg или png
  • image_urls: референсные изображения для модели редактирования, до 10 изображений
  • callback_url: необязательная HTTPS-точка для уведомлений о завершении

Текущую схему параметров смотрите в актуальной документации API.

1. Создайте API-ключ

Создайте аккаунт Poyo.ai, откройте раздел управления API-ключами и сохраните ключ в переменной окружения. Никогда не размещайте рабочий ключ в клиентском коде браузера и не добавляйте его в Git.

export POYO_API_KEY="your-api-key"

2. Отправка запроса Text-to-Image

Все задачи используют единый endpoint отправки:

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

Ответ содержит ID задачи:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Вызов Seedream 5.0 Pro через JavaScript

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

Используйте 2K, когда разрешение важнее фиксированного соотношения сторон. Используйте значение соотношения сторон, если формат размещения является главным ограничением.

4. Вызов Seedream 5.0 Pro через Python

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. Редактирование изображений с несколькими референсами

Измените ID модели и укажите image_urls. Опишите модели, какой вклад вносит каждое референсное изображение.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

Для надежного редактирования разделяйте промпт на три части: роли референсов, необходимые изменения и ограничения по сохранению исходного изображения.

6. Получение результата

Отправка выполняется асинхронно. После получения task_id можно:

  • опрашивать единый endpoint Poyo.ai для проверки статуса задачи; или
  • указать callback_url и обрабатывать webhook-уведомление о завершении.

Используйте документацию по управлению задачами, чтобы узнать текущий маршрут статуса и структуру ответа. В продакшене используйте экспоненциальную задержку между запросами вместо непрерывного опроса.

Обработка ошибок

Явно обрабатывайте следующие случаи:

  • 400: некорректные параметры модели, неподдерживаемые размеры, недоступные URL изображений или неверный JSON
  • 401: отсутствующий или недействительный API-ключ
  • неудачная асинхронная задача: генерация завершилась ошибкой после корректной отправки
  • повторная отправка webhook: одно и то же событие завершения может быть доставлено несколько раз

Сохраняйте ID задачи вместе с внутренним ID задания, обеспечьте идемпотентность обработки webhook и записывайте сообщения об ошибках провайдера без сохранения секретных данных в логах.

Чек-лист для продакшена

  • Храните API-ключи только на стороне сервера.
  • Проверяйте длину промпта и типы URL изображений перед отправкой.
  • Используйте HTTPS-ссылки на референсные изображения, доступные сервису генерации.
  • Устанавливайте тайм-ауты запросов при отправке задач.
  • Повторяйте временно неудачные сетевые запросы, но не выполняйте автоматические повторы для некорректных запросов.
  • Отслеживайте стоимость как number of requested outputs × 15 credits по текущему тарифу.
  • Проверяйте сгенерированный текст, детали продуктов и фактические утверждения перед публикацией.
  • Добавьте модерацию контента, соответствующую вашему продукту и рынку.

Когда использовать Pro вместо Lite

Используйте Seedream 5.0 Pro для структурированных дизайнов, сложных макетов, многоязычного текста и контролируемого редактирования. Используйте Seedream 5.0 Lite для более дешевых и массовых задач генерации изображений, где точность дизайна уровня Pro не требуется.

Для нетехнического обзора прочитайте возможности и цены Seedream 5.0 Pro. Также вы можете визуально протестировать API payload на странице модели Seedream 5.0 Pro.

Часто задаваемые вопросы

Какой endpoint API Seedream 5.0 Pro?

Отправляйте задачи генерации и редактирования на POST https://api.poyo.ai/api/generate/submit.

Какой ID модели для редактирования?

Используйте seedream-5.0-pro-edit и добавьте одно или несколько значений в input.image_urls.

Сколько референсных изображений поддерживается?

Текущая документация Poyo.ai поддерживает до 10 референсных изображений для редактирования в Seedream 5.0 Pro.

Сколько стоит одно изображение через API?

Текущая цена Poyo.ai составляет 15 кредитов, примерно $0.075, за каждое сгенерированное или отредактированное изображение.

Share: