APIMart
APIMart

Как генерировать изображения с Seedream 5.0 Pro

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

Туториал

Чтобы запустить Seedream 5.0 Pro, нужны один POST-запрос, один API-ключ и ещё один шаг: отправить задачу, получить task_id и проверять задачу, пока изображение не будет готово. Seedream 5.0 Pro работает асинхронно, поэтому в первом ответе изображения никогда нет.

Коротко:

  • Отправляю запросы на https://api.apimart.ai/v1/images/generations
  • Добавляю Authorization: Bearer YOUR_API_KEY
  • Указываю model = seedream-5-0-pro
  • Передаю prompt, а также resolution (1K, 1.5K или 2K) и size (auto или соотношение сторон вроде 16:9)
  • Для редактирования или объединения изображений добавляю до 10 референсов в image_urls
  • Опрашиваю GET /v1/tasks/{task_id} каждые 5–10 секунд, пока статус не станет completed
  • Сразу скачиваю результат, потому что ссылки на изображения действуют 72 часа

Главное, что стоит запомнить: это модель одного изображения. Каждый запрос возвращает одно изображение, а n больше 1 отклоняется. Попробовать Seedream 5.0 Pro API можно на APIMart, полный список полей — в справочнике API.

APIMart
Seedream 5.0 Pro API: шпаргалка по запросу и опросу

Ключевые выводы

  • Seedream 5.0 Pro вызывается POST-запросом на https://api.apimart.ai/v1/images/generations с заголовком Authorization: Bearer YOUR_API_KEY и model = seedream-5-0-pro.
  • Уровень вывода задаётся через resolution (1K, 1.5K или 2K), а форма — через size: auto, одно из десяти соотношений сторон или точные пиксели. 1.5K стоит столько же, сколько 1K; 3K и 4K возвращают 400.
  • Каждый запрос создаёт одно изображение. n больше 1, групповая генерация, стриминг и веб-поиск отклоняются с кодом 400, и задача не создаётся.
  • Для редактирования изображений до 10 референсов передаются через image_urls — публичными URL или Data URI в Base64.
  • Первый ответ содержит только task_id. Опрашивайте эндпоинт задач каждые 5–10 секунд и сохраните изображение в течение 72 часов.

Быстрое сравнение

РежимДля чего я его используюКлючевое ограничение или примечание
Текст в изображениеНовые изображения только по промптуВходное изображение не нужно
Редактирование по одному референсуИзменить фон, свет или детали одного изображенияОдин элемент в image_urls
Редактирование по нескольким референсамОбъединить людей, одежду или сценыДо 10 референсов
Разложение на слоиРазбить постер на редактируемые слоиРовно одно входное изображение, до 16 PNG-слоёв
Прозрачный фонРедактировать слой с сохранением альфа-каналаОдно входное изображение с альфа-каналом, output_format: "png"

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

1. Настройка доступа к API и аутентификации

1.1 Создайте аккаунт APIMart и получите API-ключ

APIMart

Зарегистрируйтесь в APIMart, откройте в личном кабинете страницу управления API-ключами и создайте ключ. Сразу скопируйте его и сохраните на стороне сервера — в менеджере секретов или переменной окружения.

Никогда не размещайте ключ во фронтенд-коде или публичном репозитории: любой, у кого он есть, сможет тратить ваш баланс. В Node.js читайте его из process.env.APIMART_API_KEY, в терминале используйте export APIMART_API_KEY="your-key-here".

1.2 Задайте базовый URL и заголовок аутентификации Bearer

Все запросы идут на базовый URL https://api.apimart.ai и содержат два заголовка:

ЗаголовокЗначение
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Сохраняйте префикс Bearer ровно с одним пробелом. Отсутствующий или неверно оформленный токен возвращает 401. Если cURL работает, а ваше приложение нет, ошибка обычно в том, как приложение формирует заголовки.

2. Сборка запроса изображения Seedream 5.0 Pro

APIMart

2.1 Основные поля: Model, Prompt, Resolution и Size

Запросу «текст в изображение» нужны model и prompt. Ещё два поля управляют результатом:

  • model: seedream-5-0-pro (seedream-5.0-pro тоже принимается).
  • prompt: описание на естественном языке. Помимо китайского и английского, модель нативно рисует текст на русском, японском, корейском, испанском, португальском, французском, немецком, индонезийском, вьетнамском и других языках. Держитесь в пределах примерно 600 английских слов: слишком длинные промпты теряют детали.
  • resolution: 1K (по умолчанию), 1.5K или 2K. 1.5K стоит столько же, сколько 1K, поэтому обычно это лучший выбор.
  • size: auto (по умолчанию), одно из десяти соотношений (1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9) или точные пиксели вроде 2048x1024. Точные пиксели должны давать в сумме от 921 600 до 4 624 220 при соотношении сторон от 1:16 до 16:1.

Например, resolution: "1.5K" вместе с size: "16:9" возвращает изображение 2048×1152.

2.2 Необязательные поля

Необязательный параметрТипКогда использовать
image_urlsArrayРедактирование и композиция по нескольким референсам; до 10 публичных URL или Data URI в Base64
output_formatStringjpeg (по умолчанию) или png
backgroundStringtransparent, чтобы сохранить альфа-канал при редактировании одного изображения, у которого он уже есть (нужен png)
layer_decompositionBooleanРазложить одно изображение на базовое и до 16 прозрачных PNG-слоёв
optimize_prompt_optionsObjectОптимизация промпта; поддерживается только {"mode": "standard"}
watermarkBooleanДобавить пометку «создано ИИ» в правом нижнем углу
nsfw_checkBooleanПроверить промпт и входные изображения перед отправкой задачи

Каждый референс может быть в формате jpeg, png, webp, bmp, tiff, gif, heic или heif, до 30 МБ и 36 млн пикселей. Первый референс бесплатный, за каждый следующий взимается фиксированная доплата.

Чтобы точно указать место правки, напишите координаты в промпте: <point>x y</point> для точки или <bbox>x1 y1 x2 y2</bbox> для области.

2.3 Поля, которые эта модель отклоняет

Seedream 5.0 Pro — модель одного изображения. Такие запросы возвращают 400, не создают задачу и не тарифицируются:

  • n больше 1 или sequential_image_generation (для групповых изображений используйте Seedream 5.0 Lite)
  • stream или tools (стриминг и веб-поиск не поддерживаются)
  • больше 10 элементов в image_urls
  • неподдерживаемые уровни вроде 3K или 4K либо соотношения сторон вне списка выше

2.4 Примеры вызовов на cURL и JavaScript

Минимальный cURL-запрос для одного изображения 16:9 на уровне 1.5K:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "resolution": "1.5K",
    "size": "16:9"
  }'

Ответ только подтверждает задачу:

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

А вот редактирование по нескольким референсам в Node.js через fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-5-0-pro",
    prompt: "Replace the outfit in image 1 with the outfit in image 2",
    image_urls: ["https://example.com/person.jpg", "https://example.com/dress.jpg"],
    resolution: "2K",
    size: "auto",
  }),
});

const { data } = await response.json();
const taskId = data[0].task_id;

Выполняйте эти вызовы на сервере, а не в клиентском коде.

3. Опрос задачи и сохранение изображения

3.1 Проверьте статус задачи

Отправьте GET https://api.apimart.ai/v1/tasks/{task_id} с тем же заголовком Authorization. Seedream 5.0 Pro ставит качество на первое место, поэтому задача может занять несколько минут. Опрашивайте каждые 5–10 секунд и задайте тайм-аут клиента около 5 минут.

Прекращайте опрос, когда status становится completed или failed. За неудачные задачи деньги возвращаются полностью.

3.2 Прочитайте результат

Завершённая задача выглядит так:

{
  "code": 200,
  "data": {
    "id": "task_01JFXYZ123456789ABCDEF",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
          "expires_at": 1784696685
        }
      ]
    }
  }
}

Изображение берётся из data.result.images[0].url[0]. В ответе также есть cost задачи. Ссылки действуют 72 часа (expires_at — метка времени Unix), поэтому скачайте файл и перенесите его в своё хранилище, а не сохраняйте только URL.

3.3 Полный пример на Python

import os
import time

import requests

BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-pro",
        "prompt": "A product poster with the headline SUMMER SALE in bold letters",
        "resolution": "1.5K",
        "size": "3:4",
        "output_format": "png",
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"][0]["task_id"]

while True:
    task = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers, timeout=30).json()["data"]
    if task["status"] == "completed":
        image_url = task["result"]["images"][0]["url"][0]
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", {}).get("message", task["status"]))
    time.sleep(5)

with open("seedream-5-0-pro.png", "wb") as f:
    f.write(requests.get(image_url, timeout=60).content)

4. Три распространённых сценария работы с изображениями

  • Постеры и графика с текстом. Возьмите нужный текст в кавычки внутри промпта, опишите макет (например, «вертикальный постер, заголовок сверху») и используйте resolution: "1.5K" с фиксированным соотношением вроде 3:4. Переходите на 2K только для финальных материалов: этот уровень дороже.

  • Редактирование по нескольким референсам. Передайте изображения человека, товара или сцены в image_urls и называйте их в промпте по порядку («изображение 1», «изображение 2»). При size: "auto" соотношение сторон результата следует за референсами. Координаты <bbox> помогают точно указать, где должен оказаться элемент.

  • Разложение на слои и прозрачные правки. Отправьте один PNG или JPEG с layer_decomposition: true, чтобы получить базовое изображение и до 16 прозрачных PNG-слоёв с данными о положении и порядке наложения. Чтобы отредактировать один слой, отправьте его обратно с background: "transparent" и output_format: "png". Задачи со слоями оплачиваются за каждое полученное изображение после предварительной блокировки средств, а излишек возвращается.

5. Итоговый чек-лист для надёжной интеграции Seedream 5.0 Pro

Аутентификация и безопасность ключа. Храните ключ в переменной окружения или менеджере секретов и вызывайте API только с бэкенда.

Проверяйте параметры перед отправкой. Используйте seedream-5-0-pro, не передавайте n (или задайте 1), держите image_urls не больше 10 и используйте только 1K, 1.5K или 2K с поддерживаемым size.

Проектируйте под асинхронный поток. Опрашивайте каждые 5–10 секунд, задайте тайм-аут клиента около 5 минут и обрабатывайте задачи со статусом failed.

Относитесь к доставке как к задаче хранения. Скачивайте каждое изображение сразу после успешного завершения задачи: ссылки истекают через 72 часа.

Проверьте стоимость перед масштабированием. Результат оплачивается поштучно по уровню пикселей (1K и 1.5K — по более низкой цене, 2K дороже), а каждый референс после первого добавляет доплату. Перед большими пакетами посмотрите актуальную таблицу цен.

Частые вопросы

Как проверить задачу изображения после получения task_id?

Отправьте GET https://api.apimart.ai/v1/tasks/{task_id} со своим заголовком Authorization: Bearer.

Опрашивайте каждые 5–10 секунд, пока status не станет completed, затем возьмите изображение из data.result.images[0].url[0]. Если статус failed, посмотрите поле error; за неудачные задачи деньги возвращаются.

Можно ли получить несколько изображений или вывод в Base64 за один запрос?

Нет. Seedream 5.0 Pro возвращает одно изображение на запрос, а n больше 1 отклоняется с кодом 400. Для нескольких вариантов отправьте несколько запросов или используйте Seedream 5.0 Lite для групповой генерации.

Результат всегда возвращается в виде URL; формат jpeg или png выбирается через output_format. Base64 поддерживается для входных изображений в image_urls, но не для вывода.

Как лучше всего не потерять сгенерированные изображения?

Ссылки на изображения действуют 72 часа, а expires_at в результате показывает точное время истечения.

Скачивайте каждое изображение в своё хранилище, как только задача перейдёт в completed, и сами сохраняйте task_id. Не считайте возвращённый URL постоянным хранилищем.

Теги#Seedream 5.0 Pro#генерация изображений#руководство по API#разработчики

О команде APIMart

Команда APIMart пишет обзоры моделей, сравнения и разборы цен для разработчиков, которые создают продукты на базе ИИ. APIMart даёт один API для моделей чата, изображений и видео от разных провайдеров, поэтому модели из этой статьи можно сравнить между собой до запуска.

Готовы попробовать?

Выберите нужную модель в маркетплейсе моделей

Попробуйте чат, изображения и видео в маркетплейсе APIMart и быстро оцените возможности моделей через единый API.

Чат-моделиМодели изображенийВидео-модели
Открыть маркетплейс моделей