Руководство
Как использовать seedream-4.5/text-to-image через HiAPI API: примеры на curl и Python
Практическое руководство для разработчиков по минимальной рабочей интеграции
На этой странице
Что даёт seedream-4.5/text-to-image
seedream-4.5/text-to-image — это эндпоинт генерации изображений из текста, доступный через HiAPI API. Вы отправляете текстовый промпт и несколько необязательных параметров, а модель возвращает сгенерированное изображение. Его можно использовать для создания иллюстраций сцен, макетов продуктов, концепт-арта или любого визуального контента, где нужно отрисовать читаемый текст внутри изображения — вывески, этикетки, короткие заголовки. Эндпоинт не сохраняет состояние: каждый запрос — это независимая генерация, поэтому контроль над повторами и вариациями остаётся в коде вашего приложения.
Поскольку он работает за тем же единым интерфейсом, что и другие модели HiAPI, вам нужно аутентифицироваться один раз, использовать тот же базовый URL и те же соглашения об ошибках, а при смене модели не придётся изучать новый шаблон интеграции. Страница сведений о модели seedream-4.5/text-to-image содержит актуальные имена параметров и допустимые значения — считайте эту страницу авторитетным источником по полям, а не эту статью.
Структура запроса: что отправляется и что возвращается
Каждый вызов генерации изображений из текста имеет одинаковую структуру: POST-запрос к эндпоинту модели HiAPI с JSON-телом. Тело содержит поля, необходимые модели; ответ содержит сгенерированное изображение и метаданные о запросе.
Что отправляется
prompt(строка, обязательный): описание изображения. Это основной инструмент управления; см. раздел о промптах ниже.aspect_ratioили поле, связанное с размером (необязательный): определяет форму выходного холста. Используйте точное имя поля со страницы модели — не предполагайте, что оно совпадает с параметрами других моделей.- Любые специфические для модели параметры, описанные на её странице (например, подсказки по стилю или качеству). Опускайте ненужные поля; API применит значения по умолчанию.
Что возвращается
Успешный ответ — это JSON-объект. Поля, которые ваш код фактически будет читать, обычно такие:
- Данные изображения: в зависимости от схемы ответа это может быть URL сгенерированного изображения или строка изображения в кодировке base64. Код должен обрабатывать тот формат, который реально возвращает эндпоинт; страница модели указывает, какой именно.
- Метаданные запроса, например идентификатор или статус — полезны для журналирования и поддержки.
Не все поля гарантированы во всех версиях, поэтому проверяйте структуру ответа, а не полагайтесь на фиксированную схему. Если ваш парсер ищет только нужные поля, а остальные считает необязательными, интеграция выдержит незначительные изменения ответа.
Ваш первый рабочий запрос curl
Минимальный корректный вызов отправляет только промпт и ничего больше. Замените ключ-заполнитель и промпт на свои и запустите его.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "тихое уличное кафе в сумерках, тёплый свет из окон, грифельная вывеска с надписью OPEN",
"aspect_ratio": "1:1"
}'
Построчное пояснение:
- URL указывает на эндпоинт HiAPI этой модели. Идентификатор модели должен в точности совпадать с документацией.
- Заголовок
Authorizationнесёт ваш API-ключ. Использование переменных окружения позволяет ключу не попадать в историю оболочки и исходные файлы. Content-Type: application/jsonсообщает серверу, что тело запроса нужно разбирать как JSON.- JSON-тело содержит промпт и необязательное соотношение сторон. Начните с одного изображения и одного промпта; итерируйте формулировку, прежде чем добавлять параметры.
При успешном вызове ответ будет содержать данные изображения, описанные в предыдущем разделе. Сохраните результат в файл (или откройте возвращённый URL) и проверьте его, прежде чем двигаться дальше. Если возникает ошибка аутентификации, убедитесь, что ключ существует и заголовок написан правильно; если ошибка параметра — сверьте имена полей со страницей модели.
Тот же запрос на Python
Версия на Python использует стандартную библиотеку requests — SDK не нужен.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "тихое уличное кафе в сумерках, тёплый свет из окон, грифельная вывеска с надписью OPEN",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
Здесь важны две детали. Во-первых, передавайте json=payload, а не строку, собранную вручную — requests сам задаст тип содержимого и корректно сериализует данные. Во-вторых, задайте явный timeout. Генерация изображений может занимать больше времени, чем типичный API-вызов, поэтому щедрый таймаут с явным режимом отказа лучше зависшего запроса.
Выводимый результат — это сырой ответ. В реальном коде извлеките поле изображения, которое возвращает ваш эндпоинт (URL или base64), затем либо скачайте этот URL вторым запросом, либо декодируйте base64 в байты и запишите на диск. Поместите эту логику извлечения в небольшую вспомогательную функцию, чтобы тестовый и производственный код использовали один и тот же парсер.
Составление промптов для реализма и читаемого текста
Качество промпта влияет на результат сильнее любого другого параметра. Две самые частые цели — фотореалистичные сцены и чётко читаемый текст внутри изображения.
Реализм
Описывайте сцену так, как фотограф выстраивает кадр: субъект, свет, время суток, ощущение объектива и окружение. Конкретные существительные лучше абстрактных прилагательных. Вместо «хорошая кофейня» напишите «узкий интерьер кофейни, полуденный свет через большие окна, деревянная стойка, малая глубина резкости». Добавьте короткую стилевую подсказку, например «photograph» или «documentary photo», чтобы направить модель прочь от иллюстративного стиля. Держите в каждом промпте одного главного субъекта; конкурирующие субъекты часто дают хаотичную композицию.
Читаемый текст
Когда изображение должно содержать текст, заключайте точный текст в кавычки и делайте его коротким. Вывеска с надписью OPEN или этикетка с FRESH BREAD гораздо надёжнее, чем целый абзац. Указывайте, где появляется текст — «грифельная вывеска над стойкой с надписью OPEN» — чтобы модель понимала, что текст принадлежит объекту. Если текст получается искажённым, сократите его, упростите окружающую сцену и сгенерируйте заново. Небольшие правки формулировки — это нормально; ожидайте нескольких итераций.
Итерации
Меняйте по одной переменной за раз: сначала промпт, затем соотношение сторон, затем любые стилевые параметры. Сохраняйте свои промпты и настройки, давшие хорошие результаты. Эта запись станет вашей базовой линией для повторной генерации и не даст отладке превратиться в угадывание.
Выбор соотношения сторон и параметров вывода
Соотношение сторон определяет композицию ещё до того, как модель что-либо нарисует. Выбирайте его под целевую задачу, а не под значение по умолчанию.
- Квадрат (
1:1): посты в соцсетях, аватары, плитки товаров. Просто и безопасно. - Горизонтальное (например,
16:9): баннеры, ключевые визуалы, слайды презентаций. Поощряет широкие сцены — горизонты, витрины, просторные интерьеры. - Вертикальное (например,
9:16): экраны мобильных устройств, истории, постеры. Лучше всего работают промпты с явным вертикальным субъектом — стоящий человек, высокое здание.
Если ваш промпт описывает широкую сцену, а вы запрашиваете вертикальный холст, модели придётся обрезать или искажать композицию. Описание должно соответствовать формату. Для последующих конвейеров генерируйте в размере, подходящем для самого крупного случая использования, и уменьшайте позже; увеличение маленьких изображений редко выглядит правильно. Когда нужны несколько форматов, делайте отдельные вызовы для каждого соотношения, а не обрезайте одно изображение под разные макеты.
Параметры вывода помимо соотношения сторон (подсказки по качеству, управление стилем) зависят от модели. Задавайте только то, что описано на странице модели, и относитесь к каждому дополнительному параметру как к переменной, которую нужно проверить, а не как к значению по умолчанию, которое нужно скопировать.
Обработка ошибок и ограничений скорости
Отказы в производственной интеграции предсказуемы: неверный ключ, недопустимые параметры, таймауты и ограничение скорости. Обрабатывайте каждый тип явно.
Проверяйте до разбора
Сначала проверьте HTTP-код состояния. 2xx означает успех — затем разбирайте тело ответа. 4xx обычно означает, что проблема в вашем запросе: неавторизованный ключ, некорректный JSON или неподдерживаемое значение параметра. Такие проблемы не решатся повтором; залогируйте тело ответа, сообщите об этом вызывающему коду и исправьте запрос. 5xx означает проблему на стороне сервера, обычно временную.
Повтор с задержкой
Повторяйте только те сбои, которые могут завершиться успешно позже: ответы 429, таймауты, ошибки соединения и большинство кодов 5xx. Используйте экспоненциальную задержку с джиттером — начинайте с короткого базового интервала, удваивайте его с каждой попыткой и ограничьте общее число попыток. Никогда не повторяйте 400 или 401; вы лишь впустую потратите квоту.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # сетевая ошибка: повторить ниже
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"Неустранимо: {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("Попытки исчерпаны")
Соблюдайте ограничения
Держите объём запросов ниже лимита скорости, указанного для вашего аккаунта, и воспринимайте 429 как сигнал замедлиться, а не повторять с большей силой. Добавьте ограничение параллелизма в воркеры и логируйте идентификатор запроса для каждой попытки, чтобы потом диагностировать ограничения скорости и сбои. Поскольку вызовы изображений тарифицируются по сгенерированному выводу, повторы, приводящие к генерации, не бесплатны — проверяйте входные данные перед запросом.
От тестовых вызовов к производственному чек-листу
Перед запуском в эксплуатацию проверьте следующие эксплуатационные моменты:
- Управление ключами: ключи хранятся в переменных окружения или менеджере секретов, никогда — в системе контроля версий. Ротируйте их по расписанию и немедленно при любом подозрении на утечку.
- Таймауты: у каждого исходящего вызова есть явный таймаут, и у вашего вызывающего кода есть план на случай его срабатывания.
- Журналирование: для каждого вызова фиксируйте идентификатор запроса, версию промпта, параметры, статус и задержку. При необходимости маскируйте ключи и полные полезные данные.
- Версионирование промптов: сохраняйте промпты и настройки, давшие принятые результаты, для воспроизведения и отката.
- Осознание затрат: генерация тарифицируется по выводу, поэтому ограничивайте размер пакета, избегайте лишних повторов и кешируйте результаты, которые будете использовать повторно.
- Изящная деградация: когда генерация после повторов всё равно не удалась, откатывайтесь к кешированному изображению или заглушке, а не ломайте страницу.
Начните с одного вызова curl из этого руководства, перенесите его в небольшую вспомогательную функцию Python и только затем добавляйте параллелизм и пакетную обработку. По мере масштабирования интеграции страница справочника модели seedream-4.5/text-to-image остаётся местом, где проверяют имена полей.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий