Как использовать Seedream 5.0 Pro Image API

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

Вот короткая версия:

• Я отправляю запросы на https://api.apimart.ai/v1/images/generations
• Я добавляю Authorization: Bearer YOUR_API_KEY
• Я задаю model как doubao-seedream-5-0-pro
• Я включаю prompt, size и n
• Я использую text-to-image для новых идей изображений
• Я использую image-to-image, когда хочу, чтобы результат оставался ближе к одному или нескольким референсным изображениям
• Я сохраняю URL изображений быстро, потому что они истекают через 24 часа
• Я использую асинхронные задачи для медленных результатов вроде изображений 3K, которые могут занимать около 35–50 секунд
• Я слежу за стоимостью, поскольку цена составляет около $0.0320 за изображение

Главное, что я бы запомнил: держите ключ на сервере, передавайте n как число и используйте опрос или вебхук для более длинных задач.

Несколько деталей важнее, чем кажется. Например, 401 часто означает, что ключ отсутствует или формат Bearer неверный. 403 часто означает, что ключ работает, но аккаунт не может использовать модель или имеет низкий баланс. А если я использую вывод Base64, мне нужно самому добавить префикс data:image/...;base64, перед показом в браузере.

Краткое сравнение

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

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

2.1 Создайте аккаунт APIMart и сгенерируйте ключ API

Перейдите на сайт APIMart и зарегистрируйте новый аккаунт ^[8]. Затем откройте страницу управления ключами API в панели управления и сгенерируйте ключ API ^[1][5].

Скопируйте этот ключ сразу же и храните его на стороне сервера. Менеджер секретов или переменная окружения — самое безопасное место для него.

Никогда не помещайте ключ API во фронтенд-код или публичный репозиторий. Если кто-то получит этот ключ, он сможет использовать ваш аккаунт. В Node.js храните его через process.env.API_KEY. В shell-окружении используйте export API_KEY="your-key-here" ^[1][6].

Прежде чем строить полный поток запросов, отправьте небольшой POST-запрос, чтобы убедиться, что доступ работает ^[1][2]. Если вы получаете ответ 200 OK, ваш ключ и права настроены правильно.

После этого можно переходить к полям запроса, включая модель и промпт.

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

Как только вы выбрали режим T2I или I2I и подготовили ключ, вам нужно настроить аутентификацию, прежде чем любой запрос изображения заработает. Отправляйте эти заголовки с каждым запросом:

Префикс Bearer важен. Пропустите его, и запрос завершится неудачей ^[2][5]. Также используйте ровно один пробел после Bearer.

HTTP-коды статусов помогают быстро выявить проблемы с авторизацией ^[1][10]. Ошибка 401 Unauthorized обычно означает, что ключ отсутствует, недействителен или не был включён префикс Bearer ^[1][10]. Ошибка 403 Forbidden обычно означает, что сам ключ действителен, но у аккаунта нет доступа к модели или достаточного баланса ^[1][10].

Хороший способ это перепроверить — сначала протестировать через cURL. Если cURL работает, а ваше приложение нет, баг, скорее всего, в коде запроса вашего приложения ^[2][6].

Когда авторизация настроена, следующий шаг — сборка тела запроса изображения.

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

3.1 Обязательные поля: модель, промпт, размер и количество изображений

Когда авторизация настроена, следующий шаг — сборка тела JSON.

Валидному телу запроса нужны четыре поля: model, prompt, size и n.

Для Seedream 5.0 Pro задайте model как doubao-seedream-5-0-pro ^[1]. Поле prompt принимает описание на естественном языке и поддерживает до 5,000 символов ^[2]. Поле size управляет размерами вывода или соотношением сторон. Распространённые значения включают 1024x1024, 2K и соотношения сторон вроде 1:1 или 16:9 ^[1][2]. Поле n задаёт, сколько изображений генерировать, обычно от 1 до 15 ^[1][6].

Одна мелкая деталь может подставить людей: n должно быть целым числом, а не строкой. Если вы передадите "1" вместо 1, API вернёт ошибку валидации ^[1][5].

3.2 Опциональные поля: референсные изображения, веб-поиск и асинхронные задачи

image_urls — главное поле для режима image-to-image. Используйте его, чтобы отправить до 14 референсных изображений как URL или Base64 data URI. Каждое изображение должно быть менее 10 МБ и использовать соотношение сторон между 1:3 и 3:1 ^[1]. Если вы используете Base64, включайте полный префикс Data URI — data:image/jpeg;base64, — иначе запрос завершится неудачей ^[1][5].

web_search может помочь с фактическими промптами или промптами реального времени, такими как текущие события или логотипы брендов ^[4][7]. Для большинства стандартных генераций изображений он вам не понадобится.

Для асинхронных или пакетных задач callback_url принимает публичный HTTPS-эндпоинт, куда APIMart отправит POST с payload о завершении задачи ^[2].

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

Вот минимальный рабочий cURL-запрос для одного изображения 1024×1024:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

А вот тот же запрос в Node.js с fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Держите этот запрос на стороне сервера. Никогда не раскрывайте ключ API в клиентском коде.

Как только вы отправите запрос, следующий шаг — разбор payload ответа.

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

4.1 Разбор URL изображений, вывода Base64 и объектов ошибок

Как только запрос завершается, форма ответа остаётся одинаковой, отправили ли вы одно изображение или несколько.

Успешный ответ возвращает JSON-объект с четырьмя полями верхнего уровня: model, created (Unix-таймстамп), data (массив объектов изображений) и usage ^[6]. Каждое сгенерированное изображение появляется внутри data как строка url или b64_json, в зависимости от запрошенного вами формата. Если n больше 1, data включает по одному объекту изображения на каждый вывод.

Если вы использовали формат URL, каждый элемент в data хранит ссылку на изображение в .url. Вы можете задать это значение как src изображения в браузере. Один нюанс: это временные подписанные ссылки, и они истекают через 24 часа ^[6]. Для продакшен-приложений скачивайте файл сразу же и сохраняйте его в постоянное хранилище вместо хранения URL.

Если вы использовали формат Base64, каждый элемент в data хранит сырую строку в .b64_json. Он не включает префикс data:image/...;base64, ^[6]. Чтобы показать его в браузере, добавьте этот префикс сами:

img.src = "data:image/png;base64", + data.b64_json;

Чтобы сохранить его как файл в Python, сначала декодируйте его:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Если запрос завершается неудачей, ответ включает поля code и message ^[6]. 400 обычно означает неподдерживаемый размер или недопустимый параметр. 401 означает, что запрос не авторизован. Логируйте оба поля каждый раз. В большинстве случаев message указывает прямо на проблему.

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

---

4.2 Три распространённых типа изображений, которые можно сгенерировать с Seedream 5.0 Pro

Эти три паттерна соответствуют режимам, рассмотренным ранее: только текст, один референс и несколько референсов.

• Только текстовые маркетинговые визуалы. Для ассетов кампании, которым нужно больше детализации, используйте разрешение 3K (size: "3K") и пишите структурированный prompt, который начинается с субъекта и компоновки сцены, затем добавляет освещение, стиль и детали цвета. Генерация 3K занимает 35–50 секунд, поэтому асинхронный режим обычно подходит лучше.

• Вариации продукта по одному референсу. Используйте режим image-to-image с одним референсным изображением в image_urls и сфокусированным prompt, который меняет только то, что вы хотите, например фон, освещение или текстуру поверхности. Это удерживает форму и детали продукта ближе к исходному изображению, чем генерация с нуля. Для вариаций 3K используйте callback_url, поскольку каждая задача может занимать около 40 секунд ^[2].

• Согласованность по нескольким референсам для бренда и персонажа. Если вам нужно, чтобы персонаж или брендированный элемент оставался согласованным на нескольких изображениях, передайте до 14 референсных изображений через image_urls ^[2][3]. Задайте sequential_image_generation в auto при создании нескольких результатов из референсных входных данных, чтобы сохранять разнообразие без потери визуальной согласованности ^[5][4]. Это хорошо работает для серий соцконтента, каталогов продуктов и листов персонажей.

Эти паттерны обычно работают лучше всего, когда формат ответа соответствует рабочему процессу.

---

4.3 Синхронные и асинхронные запросы и ответы URL против Base64

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

Для асинхронных задач подождите около 20 секунд перед первым опросом, затем проверяйте каждые 3 секунды ^[2]. В продакшене callback_url — лучший вариант, поскольку он избегает циклов опроса и снижает нагрузку на сервер ^[2][9].

Используйте ответы URL по умолчанию. Переключайтесь на Base64 только когда вам нужны данные изображения в том же ответе.

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

После первого успешного тестового вызова пройдитесь по этому чек-листу, прежде чем масштабироваться до продакшена. Это простой способ поймать проблемы, которые склонны наглухо стопорить запуски.

Аутентификация и безопасность ключа. Держите ключ API в переменной окружения или менеджере секретов. Отправляйте запросы с вашего бэкенда с Authorization: Bearer <your_key>.

Валидируйте параметры запроса перед отправкой. Проверьте строку модели, передавайте n как целое число, держите image_urls в пределах разрешённого лимита и убедитесь, что запрошенный size поддерживается.

Для задач, которые занимают дольше быстрого превью, соответственно скорректируйте путь доставки. Задавайте таймауты в зависимости от размера вывода и используйте callback_url для долгих задач вместо опроса.

Как только изображение готово, относитесь к доставке как к задаче хранения, а не просто ответа. Если вы используете вывод URL, скачивайте файл сразу же и перемещайте его в постоянное хранилище. Подписанные URL истекают через 24 часа ^[6].

Тестируйте промпты на небольшом батче перед масштабированием. Seedream 5.0 тарифицируется примерно в $0.0320 за сгенерированное изображение ^[2]. Логируйте createTime, completeTime и costTime, чтобы следить за задержкой и расходами ^[2].

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

::: faq

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

Используйте возвращённый task_id, чтобы проверить статус вашей асинхронной задачи изображения.

Отправьте GET-запрос на эндпоинт статуса, который даёт вам API. Во многих API это выглядит так:

• /v1/tasks/{task_id}
• или эндпоинт в стиле запроса с task_id

Для продакшен-использования подождите около 20 секунд после создания задачи перед первой проверкой статуса. После этого опрашивайте каждые 3 секунды, пока статус задачи не покажет completed.

Как только задача завершена, прочитайте payload ответа и извлеките из него URL изображений. :::

::: faq

Когда стоит использовать вывод URL вместо Base64?

Используйте вывод URL в большинстве случаев. Он даёт вам прямую ссылку на сгенерированное изображение, что упрощает подключение к веб- или мобильным приложениям.

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

::: faq

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

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

Seedream 5.0 Pro API работает асинхронно. Это значит, что вы не получите URL изображения сразу. Сначала вы получаете task ID. Затем используете этот task ID, чтобы получить URL изображения.

Чтобы избежать потери результата, у вас есть два основных варианта:

• Опрашивать с task ID, пока изображение не будет готово
• Использовать callback URL, чтобы ваша система могла получить, захватить и сохранить изображение до истечения ссылки

Если вы прождёте слишком долго, URL истечёт и изображение может быть потеряно. :::