Как использовать seedream-5.0-flash через hiapi API: curl, Python и готовый к запуску запрос

Что вы создадите

Рабочую интеграцию, которая вызывает модель изображений seedream-5.0-flash от hiapi через curl и Python: отправляет запрос на генерацию изображения по тексту (или на редактирование изображения), опрашивает результат и скачивает URL вывода. В итоге вы получите скрипт, который можно сразу вставить в собственный проект.

Предварительные требования

• Учётная запись hiapi и API-ключ. Получите его в консоли hiapi — ключ имеет вид sk-....
• curl или Python 3.8+ (pip install requests).
• Библиотека для редактирования изображений не нужна — seedream-5.0-flash принимает чистый промпт или промпт плюс URL входного изображения для редактирования.

Полная справка по модели: seedream-5.0-flash на hiapi и страница документации API.

Минимальный рабочий пример

hiapi предоставляет все модели генерации через единую конечную точку: вы создаёте задачу, затем опрашиваете её (или получаете обратный вызов) до завершения.

curl

# 1. Создать задачу
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. Опрашивать до завершения
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

Пояснения к объекту input:

• prompt (обязательно, 1–5000 символов) — что сгенерировать или, если вы также передаёте image, что изменить.
• image (необязательно, строка или массив до 10 URL/base64-URI data:image/...) — передайте этот параметр, чтобы редактировать/использовать существующее изображение как референс, а не генерировать с нуля. Опустите для чистой генерации по тексту.
• size (необязательно, по умолчанию "2K") — одно из предустановленных значений 1K / 1.5K / 2K, или пользовательская строка WIDTHxHEIGHT, например "1536x1024" (общее число пикселей 921 600–4 624 220, соотношение сторон от 1:16 до 16:1).
• output_format (необязательно) — "jpeg" или "png".
• background (необязательно, по умолчанию "opaque") — установите "transparent" только при редактировании изображения с альфа-каналом.

output[].url в ответе — это подписанная ссылка с ограниченным сроком действия (поле expireAt) — скачайте или переразместите её вовремя, а не сохраняйте горячую ссылку надолго.

Шаблоны для продакшена

Использование обратного вызова вместо опроса

Для серверных интеграций пропустите опрос и позвольте hiapi уведомить вас о завершении задачи. Добавьте объект callback верхнего уровня рядом с model/input (не вкладывайте его в input):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" в настоящее время — единственное поддерживаемое значение: когда задача достигает конечного состояния (success или fail), ваш эндпоинт получает ровно один POST. Для защиты от повторных доставок удаляйте дубликаты по taskId и убедитесь, что ваш эндпоинт доступен по HTTPS, прежде чем полагаться на него в продакшене.

Опрос vs. обратный вызов

• Опрос используйте, когда прототипируете, запускаете короткоживущие скрипты или у вас ещё нет публичного HTTPS-эндпоинта. Просто, но добавляет задержку и количество запросов для медленных задач.
• Обратный вызов используйте, когда запускаете сервис — никаких лишних запросов опроса, и вы узнаёте о завершении задачи сразу. Требуется публично доступный HTTPS-URL.

Идемпотентность

Сама генерация изображений не идемпотентна (один и тот же промпт не вернёт одно и то же изображение дважды), поэтому если вашему рабочему процессу нужна семантика «повтор без двойной оплаты», отслеживайте taskId на своей стороне и перед повторной отправкой того же запроса после тайм-аута проверяйте статус задачи, а не повторяйте вслепую.

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

• 401 с permission_denied — ваш API-ключ отсутствует, имеет неверный формат или отозван:

  {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
  

  Убедитесь, что вы отправляете Authorization: Bearer sk-... (а не только сырой ключ), и что ключ не был ротирован.

• 400 с INVALID_REQUEST — какое-то поле не прошло валидацию. message точно укажет, какое поле и почему, например size вне допустимого диапазона. Исправьте это поле и отправьте заново; не повторяйте запрос как есть.

• Сбой на уровне задачи — HTTP-вызов может завершиться успешно (200), а задача после обработки всё равно завершится со status: "fail". Всегда проверяйте data.status в ответе опроса/обратного вызова, а не только HTTP-код создания.

Связанные внутренние ссылки

• Страница модели seedream-5.0-flash — цены, ограничения и панель онлайн-проб.
• Создание задачи (документация) — полная схема запроса POST /v1/tasks.
• Получение деталей задачи (документация) — структура ответа опроса и значения статусов.
• Аутентификация (документация) — как работают API-ключи и заголовки на всех эндпоинтах hiapi.
• Цены hiapi — текущая цена за изображение для seedream-5.0-flash и всех других моделей.
• Руководство по API генерации изображений по тексту seedream-5.0-pro — если вам нужен вывод более высокого разрешения, обратитесь к более точной родственной модели уровня Pro.

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

seedream-5.0-flash бесплатен? Нет — он оплачивается за изображение через ваш API-ключ hiapi. Актуальные тарифы см. на странице цен; без действующего ключа производственный доступ невозможен.

Поддерживает ли seedream-5.0-flash редактирование изображений по изображению, а не только генерацию по тексту? Да. Добавьте поле image рядом с prompt (URL или строка base64 data:image/..., или массив до 10 таких значений), и модель будет редактировать/объединять на основе референсного изображения, а не генерировать с нуля.

Почему мой запрос возвращает 200, но изображения нет? Ответ 200 от POST /v1/tasks означает лишь, что задача принята — генерация асинхронна. Опрашивайте GET /v1/tasks/<id> (или ждите обратного вызова) и проверяйте data.status; URL изображения появляется только когда status равен "success".

Могу ли я запросить пользовательское разрешение вместо 1K/1.5K/2K? Да — передайте size как "WIDTHxHEIGHT" (например "1536x1024") вместо предустановленного значения. Общее число пикселей должно быть от 921 600 до 4 624 220, а соотношение сторон — от 1:16 до 16:1, иначе запрос вернёт 400.

Что происходит с URL вывода со временем? Возвращаемый output[].url — это подписанный URL с меткой времени expireAt — это не постоянное хранилище. После успешного завершения задачи скачайте байты или скопируйте их в собственное хранилище как можно скорее.

Мой обратный вызов так и не сработал — что проверить в первую очередь? Убедитесь, что ваш callback.url — это публично доступный HTTPS-эндпоинт (не localhost и не внутренний адрес), и что callback — поле верхнего уровня в теле запроса, а не вложенное в input.