Синхронные и асинхронные запросы
Два способа вызвать API изображений: дождаться изображения в одном запросе или передать async true, сразу получить id задачи и читать задачи опросом либо через вебхук.
Изображение можно создать двумя способами. Параметры у них одинаковые, стоят они одинаково и подчиняются одним и тем же лимитам; выбирайте для каждого запроса отдельно.
| Синхронный (по умолчанию) | Асинхронный | |
|---|---|---|
| Как | Отправьте запрос и ждите | Добавьте async: true, сразу получите id задачи |
| Ответ приходит | В том же ответе, через 20 секунд — несколько минут | Позже: вы опрашиваете или мы вызываем ваш вебхук |
| Соединение остаётся открытым | Пока изображение не готово | Меньше секунды |
| Максимальное время работы | 7 минут | 10 минут |
| Возвращает | Данные изображения (b64_json) или ссылку (url) | Ссылку (url) |
| Работает с | SDK OpenAI и любым инструментом, рассчитанным на OpenAI Images API | Любым HTTP-клиентом |
| Подходит для | Скриптов, бэкендов, по одному изображению за раз | Веб-страниц, множества изображений сразу, медленных моделей, бессерверных функций с коротким лимитом времени |
Три вызова
| Вызов | Что делает |
|---|---|
POST /v1/images/generations или /v1/images/edits с async: true | Запускает задачу. Отвечает 202 с id задачи |
GET /v1/images/tasks?ids=a,b,c | Состояние до 100 задач одним запросом |
GET /v1/images/tasks/{id} | Состояние одной задачи |
1. Запустите задачу
Добавьте async: true в тело POST /v1/images/generations или как поле формы в POST /v1/images/edits.
curl https://api.cheapestimagen.com/v1/images/generations \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true}'Ответ — 202 Accepted, значительно быстрее секунды:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}Сохраните id. Три вещи, которые нужно знать:
- Только ссылки. Изображения задачи возвращаются ссылками, поэтому не указывайте
response_formatили задайтеurl.b64_jsonотклоняется с ошибкой400. - Неверные запросы отклоняются сразу, а не позже. Неправильный параметр (
400), нехватка кредитов (402) или слишком много запросов (429) обрабатываются сразу, как и в синхронном запросе. Задача не создаётся. - Нет поля в теле? Заголовок
Prefer: respond-asyncделает то же, чтоasync: true.
2. Читайте задачи
Несколько задач одним запросом
Если вы ждёте больше одной задачи, запрашивайте их все сразу. Страница, запустившая 10 задач, отправляет один запрос опроса, а не 10.
curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
-H "Authorization: Bearer YOUR_KEY"{
"object": "list",
"data": [
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "succeeded",
"created": 1795062073,
"finished": 1795062098,
"model": "gpt-image-2.6",
"result": {
"created": 1795062098,
"data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
}
},
{
"id": "req_26e50328772b7d62f59d355a",
"object": "image.task",
"status": "in_progress",
"created": 1795062074,
"finished": null,
"model": "gpt-image-2.6"
}
],
"not_found": []
}idsпринимает до 100 id задач через запятую.dataсодержит задачи в том порядке, в котором вы их запросили.- Id, который не относится к задачам вашего аккаунта или изображения которого уже не хранятся, попадает в
not_found. Запрос от этого не завершается ошибкой.
Одна задача
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"Ответ — сам объект задачи. Неизвестный id возвращает 404.
Что сообщает задача
status | Значение | Дополнительное поле |
|---|---|---|
in_progress | Изображение создаётся | нет |
succeeded | Готово | result: ровно то, что вернул бы синхронный вызов, { created, data: [{ url }] } |
failed | Не получилось | error: ровно та ошибка, которую вернул бы синхронный вызов |
Неудавшаяся задача выглядит так:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "failed",
"created": 1795062073,
"finished": 1795062110,
"model": "gpt-image-2.6",
"error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}За неудавшуюся задачу плата не берётся. Единственное исключение то же, что и для синхронных запросов: отказ на стабильных каналах Nano Banana.
Как часто опрашивать
Достаточно раз в 2–5 секунд. Чтение задач бесплатно и не считается запросом изображения: оно не учитывается среди запросов в работе. Задачу можно читать 72 часа, пока хранятся её изображения.
Пример: веб-страница, которая запускает 10 изображений
По одному запросу на каждое изображение, чтобы запустить их, затем один запрос раз в 3 секунды на все сразу.
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// Start 10 tasks.
const prompts = Array.from({ length: 10 }, (_, i) => `a red fox in the snow, variation ${i + 1}`);
const started = await Promise.all(prompts.map((prompt) =>
fetch(`${API}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
}).then((r) => r.json())
));
// Poll all of them with one request until none is in progress.
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
await new Promise((r) => setTimeout(r, 3000));
const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
waiting = waiting.filter((id) => !done[id]);
}
for (const task of Object.values(done)) {
console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}Не размещайте свой API-ключ на публичной веб-странице. Вызывайте API со своего сервера, а страница пусть обращается к нему.
Пример: Python
import time, requests
API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
ids = [
requests.post(f"{API}/images/generations", headers=HEADERS, json={
"model": "gpt-image-2.6", "prompt": f"a red fox in the snow, variation {i}", "async": True,
}).json()["id"]
for i in range(10)
]
done = {}
while len(done) < len(ids):
time.sleep(3)
waiting = [i for i in ids if i not in done]
tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})
for t in done.values():
print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])С SDK OpenAI передайте поле через extra_body={"async": True}, а задачи читайте обычным HTTP-запросом.
Вебхук вместо опроса
Добавьте webhook_url, и мы отправим на него POST с готовой задачей:
{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }- Адрес должен быть
https://с публичным именем хоста. - Тело — объект задачи, тот же JSON, что у
GET /v1/images/tasks/{id}. - Ответьте любым
2xxв течение 10 секунд. Иначе мы повторим ещё дважды, через 3 и 15 секунд, и остановимся. - Чтобы вызов был подписан, передайте в запросе свой секрет как
webhook_secret(от 16 до 128 символов). Без него вызов не подписан: считайте его уведомлением, возьмите из негоidи прочитайте задачу своим ключом, прежде чем доверять содержимому. - Задача остаётся доступной для чтения независимо от того, дошёл ли вебхук, поэтому пропущенный вызов ничего не теряет.
Проверьте подпись
С webhook_secret вызов содержит заголовок x-webhook-signature: t=1763560000,v1=5f2b…. t — время вызова в Unix-секундах, а v1 — HMAC-SHA256 в hex от текста <t>.<body> с вашим секретом. Вычислите то же значение по сырому телу запроса и сравните; отклоняйте вызовы, у которых t старше нескольких минут.
import hashlib, hmac, time
def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300import { createHmac, timingSafeEqual } from 'node:crypto';
function isOurs(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}Используйте тело ровно в том виде, в каком оно пришло, до любого разбора JSON. Секрет используется для этого одного запроса и не хранится в вашем аккаунте.
Лимиты
Асинхронный запрос считается так же, как синхронный: 300 запросов в минуту и 50 в работе на аккаунт. Запрос, отправленный, когда выполняются 50, отклоняется с ошибкой 429; дождитесь завершения одного. Чтение задач не считается.
Idempotency-Key работает так же: пока запрос с этим ключом выполняется или после его успешного завершения, повтор возвращает 409.
Соотношения и размеры
Размеры изображений, которые можно передать в поле size API Cheapest Imagen: до 19 соотношений сторон в 1K, 2K и 4K, а также свои размеры.
Лимиты запросов и массовая генерация
Лимиты запросов API Cheapest Imagen (300 в минуту, 50 одновременно), ошибка 429 и массовая генерация тысяч изображений с повторами, которые не оплачиваются дважды.