Изображения
POST /v1/generations
Создаёт асинхронное задание генерации. Юниты резервируются сразу и возвращаются, если задание не удалось.
Заголовки
| Заголовок | Обязателен | Описание |
|---|---|---|
| Authorization | да | Bearer <API-ключ> |
| Idempotency-Key | да | Уникален для каждого запроса (≤ 128 символов). Повторная отправка того же ключа возвращает исходное задание (200) без повторного списания. Тот же ключ с другим телом → 422. |
| Content-Type | да | application/json |
Тело
| Поле | Тип | Описание |
|---|---|---|
| model | string | Обязательно. Идентификатор модели из GET /v1/models, например "nanobanana". |
| prompt | string | Обязательно, если нет images. 1–2000 символов (у модели лимит может быть ниже — см. max_prompt). |
| negative_prompt | string | Необязательно. Чего избегать в изображении. Только у моделей, в схеме которых negative_prompt: true. |
| n | integer | Сколько изображений сгенерировать, 1–4. По умолчанию 1. Каждое изображение оплачивается отдельно. |
| resolution | string | 1K (по умолчанию) · 2K · 4K. Тир, в котором рендерит модель, и единица, в которой она тарифицируется. Поддерживаемые тиры модель перечисляет в params_schema.resolutions. |
| ratio | string | Соотношение сторон: auto · 1:1 (по умолчанию) · 16:9 · 9:16 · 4:3 · 3:4 · 3:2 · 2:3 · 5:4 · 4:5 · 21:9. На цену не влияет. |
| images | string[] | Необязательно. Референсные изображения для image-to-image — публичные https-ссылки. Не больше max_images модели; если поля нет в схеме модели, референсы она не принимает. |
| seed | integer | Необязательно. Тот же seed и промпт дают воспроизводимый результат, если модель это поддерживает. |
| webhook_url | string | Необязательно. https-адрес, который вызывается по завершении задания. См. «Вебхуки». |
| size | string (legacy) | Устарело. Строка WIDTHxHEIGHT, которая отображается на ближайшие resolution + ratio. Принимается только ради существующих интеграций; вместе с resolution или ratio — это 400. В новом коде используйте resolution и ratio. |
Ответ 202 Accepted
{"id": "…", "model": "nanobanana", "status": "queued", "params": {…}, "cost": 2, "created_at": "…"}Лимит размера тела 64 КБ. Неизвестные поля отклоняются с 400.
GET /v1/generations/{id}
Возвращает задание. Когда status = succeeded, ответ содержит images[] с временными ссылками на скачивание (15 минут; повторите запрос для свежих ссылок).
| status | Значение |
|---|---|
| queued | Ждёт воркера. |
| running | Генерируется. |
| succeeded | Готово; есть images[]; юниты списаны. |
| failed | Не удалось; есть error{code,message}; юниты возвращены. |
| cancelled | Отменено вами до старта; юниты возвращены. |
{"id": "…", "status": "failed", "error": {"code": "content_policy", "message": "the prompt was rejected by the content policy"}, "cost": 2, …}Чат-запросы тоже хранятся как генерации: запись содержит capability: "text.chat" и блок usage с числом токенов — но не сами сообщения, только превью последнего сообщения пользователя (≤ 200 символов) и хеш.
{"id": "…", "model": "qwen3.8-max", "capability": "text.chat", "status": "succeeded", "params": {"prompt": "Explain idempotency keys…", "messages": 2, "messages_sha256": "9f2c…", "max_tokens": 200, "stream": true}, "usage": {"prompt_tokens": 31, "completion_tokens": 58, "total_tokens": 89, "finish_reason": "stop", "usage_source": "estimated"}, "cost": 0.004, "created_at": "…", "finished_at": "…"}GET /v1/generations
Сначала новые, по 50 на страницу. Передайте cursor из предыдущего ответа, чтобы получить следующую.
curl -s "https://api.genmux.tech/v1/generations?cursor=2026-08-28T20:01:12.345Z" -H "Authorization: Bearer $API_KEY"{"data": [ {…job…}, … ], "next_cursor": "2026-08-27T09:12:44.001Z"}Фильтр по типу: ?capability=text.chat (или image.generate).
DELETE /v1/generations/{id}
Отменяет задание в статусе queued и возвращает юниты. Уже выполняющиеся задания отменить нельзя (409).
curl -s -X DELETE https://api.genmux.tech/v1/generations/<id> -H "Authorization: Bearer $API_KEY"{"id": "…", "status": "cancelled", …}