Image API

Создайте одну асинхронную задачу генерации изображения, указав постоянный ID модели BeatAPI.

На странице выбранной модели описаны все поля, значения по умолчанию, допустимые значения, правила сочетания параметров, примеры запросов, ответы и ошибки.

Список доступных моделей

GET /v1/media/models

Этот общедоступный метод не требует авторизации.

curl "https://api.beatapi.io/v1/media/models?media_type=image"

{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "gpt-image-2",
        "object": "generation_model",
        "name": "GPT Image 2",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-flare",
        "object": "generation_model",
        "name": "GPT Image 2.5 Flare",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-sunburst",
        "object": "generation_model",
        "name": "GPT Image 2.5 Sunburst",
        "media_type": "image",
        "input_modes": ["text", "image"]
      }
    ]
  }
}

Внутренняя маршрутизация к поставщикам не входит в публичный контракт.

Общие правила создания задачи

POST /v1/images/tasks

Тело запроса должно соответствовать ровно одной схеме модели. Поле model определяет схему; неизвестные поля отклоняются.

curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph on a warm stone pedestal.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

Корректный запрос возвращает 201 Created с data.id, task_kind="image", выбранной model, status="queued", данными об использовании и request_id. Проверяйте GET /v1/tasks/{task_id} каждые 5–10 секунд до succeeded или failed. Готовое изображение доступно в data.output.media[] и data.output.r2_url.

Точный повтор с тем же ключом идемпотентности возвращает уже принятую задачу. Тот же ключ с другим телом запроса даёт 409 idempotency_conflict.

Общие ошибки

Ответ с ошибкой содержит error.code, английское error.message, error.retryable, error.request_id, а при 429 — error.retry_after_seconds. Если уже принятая задача завершилась ошибкой, запрос статуса всё равно возвращает 200: проверьте data.error_code. Все коды и правила повторов описаны в разделе ошибок. Страницы отдельных моделей ниже содержат полные контракты для рабочей среды.