Оптимизация затрат Seedream API: как снизить расходы на генерацию изображений на hiapi

Seedream на hiapi доступен на четырёх разных уровнях — seedream-5.0-flash, seedream-5.0-lite, seedream-5.0-pro и устаревший seedream-4.5 — и тарификация на каждом из них различается. Выбрав неверный уровень или неверное разрешение, вы можете платить за изображение в 2–4 раза больше без какого-либо видимого улучшения качества. Это руководство показывает фактическую структуру цен на каждом уровне и даёт рабочий шаблон кода для вызова самого дешёвого уровня, который удовлетворяет вашим требованиям.

Что вы построите и предварительные требования

Вы построите небольшой Python-клиент, который создаёт задачи генерации изображений Seedream через единый API задач hiapi, ожидает результата и осознанно выбирает комбинацию разрешения/модели, а не копирует значения по умолчанию из туториала. Сначала получите API-ключ в вашей консоли hiapi — каждый запрос ниже отправляет его в виде Authorization: Bearer sk-....

Структура цен, которую вы оптимизируете

Текущая цена за изображение (всегда сверяйтесь с актуальной страницей цен перед запуском, поскольку тарифы меняются):

• seedream-5.0-flash — фиксированная $0.025 за изображение, одинаковая цена для генерации изображения по тексту и по изображению. Самый дешёвый уровень на платформе; лучше всего подходит для черновиков, миниатюр и любых сценариев, где вы перегенерируете несколько раз и выбираете финальный результат.
• seedream-5.0-lite — фиксированная $0.035 за изображение, и что важно, цена одинакова независимо от того, рендерите вы в 2K или 4K. На этом уровне с точки зрения затрат никогда нет причин запрашивать 2K — 4K является бесплатным апгрейдом.
• seedream-4.5 (устаревший) — фиксированная $0.045 за изображение для обоих эндпоинтов.
• seedream-5.0-pro — тарификация по разрешению, а не фиксированная: генерация изображения по тексту стоит $0.05 при 1K и $0.10 при 2K; генерация по изображению стоит $0.06 при 1K и $0.10 при 2K. На этом уровне именно разрешение определяет, куда реально уходит ваш бюджет — черновик в 1K стоит примерно вдвое меньше финального рендера в 2K.

Эта асимметрия и есть весь смысл оптимизации: lite поощряет запрос более высокого разрешения (бесплатно), pro наказывает за более высокое разрешение (стоимость примерно удваивается). Обращайтесь с ними по-разному в коде вызова, а не хардкодьте одно и то же разрешение везде.

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

Каждый вызов Seedream проходит через один и тот же асинхронный эндпоинт задач: создание через POST /v1/tasks, затем опрос GET /v1/tasks/{taskId} или получение webhook-колбэка. Идентификаторы моделей — простые, без префикса models/ или префикса производителя.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]  # starts with sk-
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(model: str, input_payload: dict) -> str:
    resp = requests.post(f"{BASE_URL}/tasks", headers=HEADERS,
                          json={"model": model, "input": input_payload}, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_task(task_id: str, interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data
        if data["status"] == "fail":
            raise RuntimeError(data["error"])
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout}s")


# seedream-5.0-lite: 4K costs the same $0.035 as 2K, so always ask for 4K here.
task_id = create_task(
    "seedream-5.0-lite/text-to-image",
    {"prompt": "a minimalist product photo of a ceramic mug on a wooden table", "resolution": "4K"},
)
result = wait_task(task_id)
image_url = result["output"][0]["url"]
print(image_url)

На seedream-5.0-lite параметр resolution принимает только 2K или 4K (без 1K). seedream-5.0-pro принимает 1K/2K и дополнительно требует aspect_ratio (одно из значений: 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9) — входные схемы у каждого уровня Seedream немного различаются, поэтому не считайте, что поля, принимаемые одной моделью, будут работать и в другой.

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

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

SEEDREAM_COST_USD = {
    ("seedream-5.0-flash", None): 0.025,
    ("seedream-5.0-lite", "2K"): 0.035,
    ("seedream-5.0-lite", "4K"): 0.035,   # same price — always prefer 4K
    ("seedream-5.0-pro", "1K"): 0.05,      # text-to-image; i2i 1K is $0.06
    ("seedream-5.0-pro", "2K"): 0.10,
}

def pick_model_for_draft_vs_final(is_final: bool) -> tuple[str, dict]:
    if not is_final:
        return "seedream-5.0-flash", {}  # $0.025, iterate freely
    return "seedream-5.0-pro", {"resolution": "2K"}  # $0.10, one shot at the end

Предпочитайте колбэки вместо плотного опроса. В высоконагруженных пайплайнах не вызывайте wait_task в цикле каждые несколько секунд, а добавьте callback в запрос на создание:

task_id_resp = requests.post(
    f"{BASE_URL}/tasks", headers=HEADERS,
    json={
        "model": "seedream-5.0-lite/text-to-image",
        "input": {"prompt": "...", "resolution": "4K"},
        "callback": {"url": "https://yourapp.example.com/webhooks/hiapi", "when": "final"},
    },
    timeout=30,
)

Когда задача достигает терминального состояния (success или fail), ваш обработчик webhook получает один POST, а ваш воркер не расходует запросы в цикле опроса. Если вы не можете открыть публичный HTTPS-эндпоинт (локальная разработка, внутренние инструменты), опрос остаётся более простым выбором — как только вы работаете в реальном масштабе, переходите на колбэки.

Дедуплицируйте до создания задачи, а не после. API задач тарифицируется при создании, поэтому повторные запросы (таймауты, падения воркера, повторный деплой потребителя очереди), которые заново отправляют ту же задачу, будут оплачены дважды. Перед вызовом create_task проверьте в вашем хранилище, существует ли уже задача с ключом (model, input_hash), и если она уже выполняется или успешно завершена, пропустите создание — эндпоинт задач hiapi не имеет встроенной дедупликации, поэтому это должно быть в вашем коде.

Явно обрабатывайте ошибки аутентификации. Недействительный или отозванный ключ возвращает HTTP 401 и структурированное тело ответа, а не общую страницу ошибки:

{"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}

Проверяйте именно error.code == "permission_denied", чтобы неверный ключ быстро завершался с ошибкой, а не повторялся до таймаута.

Связанные ресурсы hiapi

• Цены — текущие тарифы моделей; считайте любые числа в этой статье снимком, а не гарантией.
• Консоль API-ключей — создание и ротация ключей.
• Страницы моделей Seedream 5.0 Lite — генерация по тексту и генерация по изображению.
• Страницы моделей Seedream 5.0 Pro — генерация по тексту и генерация по изображению.
• Страница модели Seedream 5.0 Flash.
• Справочник по API асинхронных задач — полный контракт создания/опроса/колбэков.
• Документация по аутентификации — формат ключей и требования к заголовкам.

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

Какая модель Seedream самая дешёвая для быстрых черновиков или иконок? seedream-5.0-flash, фиксированная $0.025 за изображение — самый дешёвый уровень на платформе, одинаковая цена для генерации по тексту и по изображению.

Запрос 4K вместо 2K на Seedream 5.0 Lite обойдётся дороже? Нет. seedream-5.0-lite стоит фиксированную $0.035 за изображение независимо от того, равно ли resolution 2K или 4K, поэтому на этом уровне запрашивайте 4K по умолчанию.

Сколько стоит изображение в Seedream 5.0 Pro? Тарификация по разрешению: генерация по тексту — $0.05 при 1K и $0.10 при 2K; генерация по изображению — $0.06 при 1K и $0.10 при 2K. В отличие от lite, разрешение здесь действительно меняет ваш счёт.

Как избежать двойной оплаты при повторной попытке выполнения задачи? У API задач нет серверных ключей идемпотентности, поэтому дедуплицируйте на клиенте: перед вызовом create_task сохраните ключ для (model, input_hash) и пропустите создание, если этот ключ уже выполняется или успешно завершён.

Мне опрашивать или использовать webhook-колбэки? Если вы не можете открыть публичный HTTPS-эндпоинт (локальная разработка, скрипты), опрашивайте GET /v1/tasks/{taskId}. Как только вы работаете в реальном масштабе, переходите на callback.url + when: "final" — это заменяет цикл опроса одним push-уведомлением на задачу.

Что возвращается при недействительном API-ключе? HTTP 401 и {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}. Явно проверяйте этот код ошибки, а не повторяйте попытки с неверным ключом до таймаута.

Могу ли я использовать эти цены без API-ключа? Нет — каждый вызов /v1/tasks требует действительного заголовка Authorization: Bearer sk-... с реальным ключом, созданным в вашей консоли; для продакшн-генерации нет пути без ключа или без регистрации.