Использование Images API
Генерация и редактирование изображений через совместимые с OpenAI адреса API.
Обновлено
Сначала сгенерируйте одно изображение
Выберите доступную модель изображений из текущего каталога. Минимальный запрос получает один результат в base64 и сохраняет JSON-ответ:
export PROVOD_API_KEY="sk_..."
curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/generations \
-H "Authorization: Bearer $PROVOD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-image-2",
"prompt": "A clean product banner on a neutral background",
"response_format": "b64_json",
"n": 1
}' \
-o response.jsonВ типичном ответе есть массив data. Каждый его элемент содержит b64_json или url в зависимости от запрошенного и поддерживаемого формата:
{
"created": 1786651200,
"data": [
{
"b64_json": "iVBORw0KGgo..."
}
]
}Для запроса с b64_json декодируйте первый результат в файл:
node -e 'const fs = require("node:fs"); const body = JSON.parse(fs.readFileSync("response.json", "utf8")); fs.writeFileSync("image.png", Buffer.from(body.data[0].b64_json, "base64"));'Если выбранная модель поддерживает запрошенный формат url, читайте data[0].url. Успешная генерация не бывает пустой: ответ содержит хотя бы один пригодный элемент изображения.
Начните с генерации и добавляйте только опубликованные для модели опции.
Проверьте возможности до добавления опций
Отдельный каталог изображений показывает актуальные модели, доступность, операции, ограничения опций, лимиты референсов и поддержку потоковой передачи, то есть возможность получать промежуточные результаты до готовых изображений:
export PROVOD_API_KEY="sk_..."
curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
-H "Authorization: Bearer $PROVOD_API_KEY"Проверьте поля available, capabilities и supported_parameters выбранной записи. Опции aspect_ratio, size, quality, resolution, background, формат и сжатие результата зависят от модели. Например, для текущих моделей изображений Google aspect_ratio и resolution — разные настройки, а допустимые значения нужно брать из записи конкретной модели. Не переносите сочетание опций с другой модели.
Поле n задаёт число готовых изображений в пределах опубликованного диапазона модели. Оно не задаёт количество референсов для редактирования. Повторяющиеся части image[] — это упорядоченные входные изображения; их допустимое число указано в capabilities.maxReferenceImages.
Получайте поток через единый адрес
Для потоковой передачи используйте POST /v1/images, а не /v1/images/generations. Выберите доступную модель генерации, у которой каталог разрешает хотя бы одно промежуточное изображение, и отправьте запрос:
set -euo pipefail
export PROVOD_API_KEY="sk_..."
if ! IMAGE_MODELS_JSON="$(
curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
-H "Authorization: Bearer $PROVOD_API_KEY"
)"; then
printf '%s\n' "$IMAGE_MODELS_JSON" >&2
exit 1
fi
if ! PROVOD_IMAGE_MODEL="$(
jq -er '
first(
.data[]
| select(
.available == true
and .capabilities.generation == true
and .supports_streaming == true
and ((.supported_parameters.partial_images.max // 0) >= 1)
)
| .id
)
' <<<"$IMAGE_MODELS_JSON"
)"; then
printf 'No available streaming image model found in /v1/images/models.\n' >&2
exit 1
fi
export PROVOD_IMAGE_MODEL
jq -n --arg model "$PROVOD_IMAGE_MODEL" '{
model: $model,
prompt: "A clean product banner on a neutral background",
stream: true,
partial_images: 1,
n: 1
}' | curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/images \
-H "Authorization: Bearer $PROVOD_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-Каждая запись SSE состоит из строки data:. Различайте промежуточные, готовые и ошибочные записи по полю type внутри JSON. Успешный поток может содержать промежуточные и готовые изображения и заканчивается маркером [DONE]:
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"iVBORw0KGgo..."}
data: {"type":"image_generation.completed","b64_json":"iVBORw0KGgo..."}
data: [DONE]При неудаче поток может отправить запись data: с публичным кодом и сообщением об ошибке:
data: {"type":"error","error":{"code":"IMAGE_UPSTREAM_FAILED","message":"Image generation failed"}}Считайте type: error или закрытие соединения до [DONE] признаком неполного ответа. Ограниченный повтор с задержкой допустим, только если ещё не пришло ни промежуточного, ни готового изображения. После начала вывода сохраните результат и требуйте явного решения перед новым запросом: автоматический повтор может продублировать работу и расходы.
Редактируйте через multipart/form-data
Используйте POST /v1/images/edits только для модели, у которой каталог указывает поддержку редактирования. curl -F создаёт нужное тело multipart/form-data и разделитель:
export PROVOD_API_KEY="sk_..."
curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/edits \
-H "Authorization: Bearer $PROVOD_API_KEY" \
-F "model=google/gemini-3.1-flash-image" \
-F "prompt=Keep the subject and replace the background" \
-F "image[]=@reference.png" \
-F "aspect_ratio=16:9" \
-F "response_format=b64_json" \
-o response.jsonДобавляйте части image[] в нужном порядке и не превышайте текущий лимит референсов модели. Часть mask допустима только для модели, которая явно публикует поддержку маски.
Публичный код ошибки — это предназначенный для клиента код в ответе API. MODEL_PARAMETER_COMBINATION_INVALID означает, что выбранная модель не принимает запрошенное сочетание опций. MODEL_CAPABILITY_METADATA_UNAVAILABLE означает, что сервис сейчас не может проверить сочетание по метаданным возможностей. Используйте точный код и актуальные значения каталога, а не подбирайте замену наугад.
Надёжные задания и восстановление
Для больших партий используйте задания: POST /v1/images/jobs быстро возвращает 202 с ID после проверки и сохранения задания. Обработка выполняется в очереди и не привязана к соединению отправившей программы. Обычные /generations и /edits сохраняют синхронное поведение.
Создать задание и получить результат
curl --fail-with-body --max-time 30 https://api.provod.ai/v1/images/jobs \
-H "Authorization: Bearer $PROVOD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-123-image-v1" \
-d '{"model":"openai/gpt-image-2.5-flare","prompt":"A clean product banner on a neutral background","n":1}' \
-o job.json
JOB_ID=$(jq -r '.id' job.json)
curl --fail-with-body https://api.provod.ai/v1/images/jobs/$JOB_ID \
-H "Authorization: Bearer $PROVOD_API_KEY"
# After a saved output appears in data:
curl --fail-with-body --location "https://api.provod.ai/v1/images/jobs/$JOB_ID/content?index=0" \
-H "Authorization: Bearer $PROVOD_API_KEY" -o output.pngСостояния задания: QUEUED, RUNNING, COMPLETED, PARTIALLY_COMPLETED, FAILED, CANCELED. Сохраняйте поле id сразу после ответа; это ID задания для проверки состояния. request_id относится к исходному HTTP-запросу и не заменяет ID задания. Готовые файлы перечислены в data: у каждого есть content_url, media_type и byte_size. При частичном завершении скачайте доступные результаты и проверьте error_code. Не считайте пустой data признаком неудачи, пока состояние не стало терминальным.
GET состояния и скачивание готового файла не запускают новую генерацию и не создают дополнительное списание. Скачивание перенаправляет на короткоживущую ссылку; когда она истекла, снова вызовите защищённый /content. API-ключ должен иметь доступ к тому же workspace. Возвращаются только файлы, которые действительно сохранились.
Когда нужен Idempotency-Key
Заголовок необязателен. Допустимо от 1 до 200 печатных ASCII-символов без пробелов. Без него каждый POST создаёт независимое задание, которое можно отслеживать по полученному ID. Если ответ POST потерялся до получения ID, безопасный повтор без ключа гарантировать нельзя.
Для надёжных повторов сохраните ключ вместе с бизнес-операцией до первой отправки. Повтор с тем же ключом и тем же JSON-содержимым возвращает прежнее задание: ожидающее, выполняющееся или уже завершённое. Нового резерва и нового запуска не будет. Порядок полей JSON не важен. Изменение содержимого при прежнем ключе возвращает 409 IMAGE_IDEMPOTENCY_CONFLICT. Ключ действует в пределах workspace и API-ключа; не меняйте API-ключ между повторными отправками одной операции. Для намеренно новой генерации нужен новый ключ. Не создавайте новый ключ только из-за тайм-аута.
После 202 с корректным ID повторяйте только GET. Идемпотентность защищает создание задания, но не обещает ровно один запрос к внешнему поставщику при любом отказе или перезапуске worker.
Ответ API заданий содержит метаданные и ссылки для скачивания, а не b64_json из синхронного ответа, даже если этот формат указан в запросе.
Повторно использовать референсы
Один раз загрузите каждый исходный файл через POST /v1/images/input-assets с multipart/form-data, полем file и тем же API-ключом. Сохраните возвращённый id. Затем отправляйте JSON-задания с operation: "edit" и inputImageIds: ["asset_..."]. Порядок ID задаёт порядок референсов. Модель должна поддерживать редактирование и нужное количество входных изображений. Повторное использование ID не загружает те же байты заново и помогает не расходовать квоту хранения на дубли. Изменение массива ID считается изменением запроса для идемпотентности.
Для маски загрузите файл через /v1/images/input-assets с multipart-полем role=mask и передайте полученный ID как maskImageId вместе с operation=edit и inputImageIds. Для обычных референсов role можно не передавать.
Python: повтор отправки, опрос и скачивание
Пример использует httpx: эти дополнительные пути не являются стандартными методами OpenAI SDK. Задайте API_KEY своим ключом и сохраняйте operation_key в собственной очереди или БД. В примере повтор POST выполняется только при транспортной ошибке и всегда с прежним ключом. После получения ID повторяются только запросы состояния.
import os
import time
from pathlib import Path
import httpx
# Persist this key with your business operation before the first POST.
# Reuse it, and the same payload, after a network failure.
API_KEY = os.environ["PROVOD_API_KEY"]
operation_key = "post-123-image-v1"
payload = {
"model": "openai/gpt-image-2.5-flare",
"prompt": "A clean product banner on a neutral background",
"n": 1,
"response_format": "b64_json",
}
with httpx.Client(
base_url="https://api.provod.ai",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=httpx.Timeout(connect=15, read=30, write=60, pool=15),
) as client:
for attempt in range(3):
try:
response = client.post(
"/v1/images/jobs",
headers={"Idempotency-Key": operation_key},
json=payload,
)
response.raise_for_status()
job = response.json()
break
except httpx.TransportError:
if attempt == 2:
raise # Keep operation_key; resume with it later.
time.sleep(2)
job_id = job["id"]
Path("image-job-id.txt").write_text(job_id)
terminal = {"COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELED"}
for _ in range(360):
try:
response = client.get(f"/v1/images/jobs/{job_id}")
except httpx.TransportError:
time.sleep(5)
continue # Retry this GET, never create another job.
if response.status_code in {429, 500, 502, 503, 504}:
time.sleep(5)
continue
response.raise_for_status()
job = response.json()
if job["status"] in terminal:
break
time.sleep(5)
else:
raise TimeoutError(f"Keep polling job {job_id}; do not resubmit it")
for item in job["data"]:
result = client.get(item["content_url"], follow_redirects=True)
result.raise_for_status()
suffix = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}
Path(f"{job_id}-{item['index']}{suffix.get(item['media_type'], '.bin')}").write_bytes(result.content)
if job["status"] != "COMPLETED":
raise RuntimeError(f"{job['status']}: {job['error_code']}; saved outputs were downloaded")Для отправки небольшого JSON-задания и опроса начните с connect timeout 15 секунд и read timeout 30 секунд. Для загрузки референсов и скачивания больших файлов задайте время по размеру и скорости соединения. Проверяйте состояние примерно раз в 5 секунд. Истечение времени ожидания вашей программы не отменяет принятое задание: сохраните ID и продолжите опрос позже. Не отменяются при этом реальные ошибки поставщика, хранилища или истечение серверного резерва; итог нужно читать из состояния задания. В очереди одновременно допускается до четырёх активных API-заданий на workspace; при 429 не создавайте новые ключи для обхода ограничения.
Забрать результат старого синхронного запроса
Для /v1/images/generations, /v1/images/edits и единого /v1/images сохраняйте x-request-id из заголовка ответа, включая ошибки. Тайм-аут соединения или HTTP 504 не доказывает, что обработка остановилась и результата нет. Большой read timeout SDK не отключает тайм-ауты прокси.
REQUEST_ID="saved-request-id"
curl --fail-with-body "https://api.provod.ai/v1/images/requests/$REQUEST_ID" \
-H "Authorization: Bearer $PROVOD_API_KEY" -o recovered.json
CONTENT_PATH=$(jq -er '.outputs[0].content_url' recovered.json)
curl --fail-with-body --location "https://api.provod.ai$CONTENT_PATH" \
-H "Authorization: Bearer $PROVOD_API_KEY" -o output.pngЭтот read-only просмотр возвращает status, terminal, error_code и outputs с сохранёнными файлами. incomplete означает, что по доступным записям нельзя подтвердить полный результат; это не доказательство, что запрос ещё выполняется. 404 означает отсутствие доступной записи или файла, а не разрешение безопасно создать вторую генерацию. Если поставщик не вернул изображение либо сохранение не удалось, скачать его через эту ручку невозможно.
Идемпотентность заданий не распространяется задним числом на синхронные POST. Для диагностики сохраните время с часовым поясом, модель, endpoint, request ID, HTTP-статус, текст ошибки и настройки тайм-аутов клиента. API-ключи, промпты и файлы референсов присылать не нужно.
Для скачивания используйте content_url из outputs: ссылка содержит ID конкретного сохранённого файла и не меняет назначение, если остальные изображения завершатся позже.
Проверяйте фактическое списание
Читайте billing через GET /v1/images/requests/{request_id} или GET /v1/images/jobs/{job_id}. Суммы возвращаются десятичными строками с восемью знаками после запятой в валюте currency:
{
"billing": {
"currency": "RUB",
"settlement_status": "settled",
"charged_amount": "10.00000000",
"reserved_amount": "0.00000000",
"released_amount": "2.00000000",
"refund_coverage": "verified_links_only",
"refunded_amount": "1.00000000",
"net_amount": "9.00000000"
}
}charged_amount — проведённые списания за использование. reserved_amount — активный резерв; released_amount — освобождённая часть резерва, а не возврат списанных средств. settlement_status принимает pending, settled или unknown и относится к первоначальному расчёту использования. Он не равнозначен terminal генерации; после settled могут появиться более поздние возвраты.
refunded_amount включает только положительные возвраты с проверенной ссылкой на списание этой операции, в том же рабочем пространстве и валюте. refund_coverage: "verified_links_only" исключает ручные корректировки без такой связи. net_amount вычитает только эти подтверждённые возвраты и не гарантирует учёт всех ручных корректировок. При конфликтующих записях или превышении границ проверки возвратов API возвращает refund_coverage: "unknown" и null в суммах возврата и итога.
Null в сумме или unknown означают недостаточность сохранённых данных: не заменяйте их нулём или расчётной ценой. Старые записи без связей и запросы отдельного шага, чей резерв относится ко всему job, могут оставаться неизвестными; читайте задание по его ID. Для освобождённого резерва с подтверждённым нулевым использованием возможен окончательный нулевой дебет. Чтение статуса и скачивание не запускают генерацию и не меняют списания. После таймаута продолжайте опрос той же операции; фиксированный срок окончательного расчёта этим интерфейсом не обещается.