Перейти к основному содержанию
POST
/
v1
/
images
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt

Use this file to discover all available pages before exploring further.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

​
Авторизация

​
Authorization
string
обязательно
Все конечные точки требуют аутентификации Bearer TokenПолучение API-ключа:Перейдите на страницу управления API-ключами, чтобы получить ваш API-ключВключите его в заголовок запроса:
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
по умолчанию:"gpt-image-2"
обязательно
Название модели генерации изображенийФиксируется как gpt-image-2
​
prompt
string
обязательно
Текстовое описание для генерации изображения
  • Поддерживается английский и китайский, рекомендуются подробные описания
  • Перед отправкой контент проходит модерацию / проверку безопасности — нарушения отклоняются немедленно
​
n
integer
по умолчанию:"1"
Количество генерируемых изображенийДиапазон: 1
Должно быть обычным числом (например, 1), не заключайте в кавычки
​
size
string
по умолчанию:"1:1"
Соотношение сторон изображенияПоддерживаемые соотношения плюс auto, чтобы сервер автоматически выбрал подходящее соотношение:
sizeТип
autoАвтоматический
1:1Квадрат
3:2Горизонтальное
2:3Вертикальное
4:3Горизонтальное
3:4Вертикальное
5:4Горизонтальное
4:5Вертикальное
16:9Горизонтальное
9:16Вертикальное
2:1Горизонтальное
1:2Вертикальное
3:1Горизонтальное
1:3Вертикальное
21:9Горизонтальное
9:21Вертикальное
Размеры в пикселях также можно передавать напрямую, например, 1881x836 / 887x1774.
Когда size установлено в auto, соотношение по умолчанию — 1:1.
​
resolution
string
по умолчанию:"1k"
Уровень разрешения выводаВарианты: 1k / 2k / 4kСопоставление size × resolution → фактические пиксели:
size1k2k4k
1:11024×1024 / 1254×12542048×20482880×2880
3:21536×10242048×13603520×2336
2:31024×15361360×20482336×3520
4:31024×7682048×15363312×2480
3:4768×10241536×20482480×3312
5:41280×1024 / 1448×10862560×20483216×2576
4:51024×1280 / 1122×14022048×25602576×3216
16:91536×864 / 1672×9412048×11523840×2160
9:16864×1536 / 941×16721152×20482160×3840
2:12048×1024 / 1774×8872688×13443840×1920
1:21024×2048 / 887×17741344×26881920×3840
3:11881×836 / 1536×5123072×10243840×1280
1:3887×1774 / 512×15361024×30721280×3840
21:92016×864 / 1915×8212688×11523840×1648
9:21864×2016 / 821×19151152×26881648×3840
4K поддерживает перечисленные выше 15 соотношений; вы также можете передавать размеры в пикселях из таблицы напрямую через size.
​
image_urls
array
Массив эталонных изображений (стандартное поле OpenAI). При наличии переключается в режим image-to-image.
Другие стандартные поля OpenAI (response_format, quality, style) не поддерживаются и игнорируются. В результатах задачи возвращается только url — при необходимости скачайте и преобразуйте в base64 самостоятельно.
​
official_fallback
boolean
по умолчанию:"false"
Использовать ли резервный официальный канал
  • false: Не использовать (по умолчанию)
  • true: Использовать официальный канал

​
Примеры использования

Text-to-image (минимальный запрос) 
{
  "model": "gpt-image-2",
  "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style"
}
Text-to-image (с соотношением + 2K) 
{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "resolution": "2k"
}
Text-to-image (вывод 4K) 
{
  "model": "gpt-image-2",
  "prompt": "An ancient castle under a starry sky",
  "size": "16:9",
  "resolution": "4k"
}
Image-to-image (эталон = URL) 
{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "https://example.com/photo.jpg"
  ]
}
Image-to-image (эталон = base64) 
{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
Image-to-image (объединение нескольких эталонов, URL + base64 в смешанном виде) 
{
  "model": "gpt-image-2",
  "prompt": "Fuse these two photos into a single poster",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

​
Response

​
code
integer
Код состояния ответа
​
data
array
Массив данных ответа

​
Запрос результатов задачи

После успешной отправки возвращается task_id. Опрашивайте статус задачи через GET /v1/tasks/{task_id}, подробнее см. в API запроса задач.

​
Пример успешного ответа

{
  "code": 200,
  "data": {
    "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
    "status": "completed",
    "progress": 100,
    "created": 1776748674,
    "completed": 1776748726,
    "actual_time": 52,
    "cost": 0.05279,
    "estimated_time": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_task_xxx_0.png"
          ],
          "expires_at": 1776835126
        }
      ]
    }
  }
}
Доступ к изображению: data.result.images[0].url[0]

​
Статусы задачи

СтатусЗначение
submittedОтправлено
processingОбрабатывается на стороне источника
completedУспех, доступно result.images
failedОшибка, см. error.message

​
Рекомендации по опросу

  • Задержка перед первым запросом: подождите 10–20 секунд после отправки перед первым запросом
  • Интервал запросов: рекомендуется 3–5 секунд, избегайте опроса с миллисекундной частотой
  • Ориентир по таймауту: одно изображение обычно генерируется за 30–60 секунд (наблюдаемое actual_time 44–53 с)
  • Пакетный запрос: для запроса нескольких задач за раз используйте POST /v1/tasks/batch с телом {"task_ids": ["task_xxx", "task_yyy"]}

​
Примечания

  1. Асинхронная обработка: при отправке возвращается task_id, опрашивайте /v1/tasks/{task_id}, чтобы получить итоговый URL изображения
  2. Модерация контента: prompt сначала проходит проверку — нарушения отклоняются без тарификации
  3. URL результата: платформа зеркалирует временные подписанные ссылки источника в собственное объектное хранилище R2, возвращая стабильную ссылку, доступную клиентам напрямую
  4. Срок действия URL: expires_at = completed + 24ч в ответе — это подсказка, своевременно скачайте или зеркалируйте на свой CDN
  5. Конфликт соотношений: используйте поле size для соотношения сторон — избегайте повторения его в prompt, чтобы не вызывать неоднозначность на стороне источника
  6. Биллинг: тарификация по уровню разрешения (1K / 2K / 4K), без оплаты при сбое или отклонении модерации
  7. Поддерживаемые соотношения для 4K: все 15 соотношений выше поддерживают 4K; также можно передавать соответствующие размеры в пикселях напрямую через size
  8. Хранение задач: task_id хранится в базе по умолчанию несколько дней (настраивается через TASK_RETENTION_DAYS) — устаревшие запросы возвращают «задача не существует или истекла»