JoyAI Image API

Документация API

Генерируйте и редактируйте изображения через один публичный API. Используйте joyai для редактирования по инструкциям или gptimage2 для text-to-image и редактирования с GPT Image 2.

Управление API-ключами Быстрый старт

Обзор

Эндпоинт

/api/v1/generate

Один эндпоинт для поддерживаемых моделей. Поведение выбирается полем model.

Auth

Bearer API-ключи

Используйте API-ключ из панели в заголовке Authorization. Серверные ключи не отправляются в браузер.

Async

Результаты по задачам

Генерация возвращает task ID. Опрашивайте status для получения URL изображений.

Аутентификация

Каждый запрос требует API-ключ в заголовке Authorization . Создайте или обновите ключи в Панель > API Keys.

Заголовок

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Модели и кредиты

model	Лучше всего для	Требуется изображение	Кредиты
`joyai`	Редактирование по инструкциям с 1–3 референсными изображениями.	Да, 1–3 URL изображений.	24 кредита за запрос.
`gptimage2`	Text-to-image и редактирование с GPT Image 2.	Необязательно. Добавьте изображения для режима редактирования.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high для 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high для 1k/2k/4k.

Быстрый старт

Отправьте запрос на POST /api/v1/generate. API сразу возвращает task ID; используйте GET /api/v1/status для опроса до успеха или ошибки.

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

Создаёт задачу генерации или редактирования. Тело запроса — JSON.

Параметры запроса

Имя	Тип	Обязательно	Описание
`model`	string	Да	Используйте joyai или gptimage2.
`prompt`	string	Да	Инструкция на естественном языке. joyai — до 1500 символов; gptimage2 — до 20000.
`images`	string[]	Обязательно для joyai; необязательно для gptimage2	URL изображений. joyai принимает 1–3; gptimage2 переходит в edit mode при наличии изображений.
`size`	string	Необязательно для joyai	Размер, например 10241024. По умолчанию 10241024.
`quality`	string	Необязательно для gptimage2	low, medium или high. По умолчанию medium.
`resolution`	string	Необязательно для gptimage2	1k, 2k или 4k. По умолчанию 1k.
`aspect_ratio`	string	Необязательно для gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 или 21:9.
`output_format`	string	Необязательно для gptimage2	png, jpeg или webp. По умолчанию png.
`callback_url`	string	Необязательно	URL для хранения с задачей в callback-процессах.

Пример JoyAI Edit

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

Пример GPT Image 2

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

Ответ

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

Опрашивайте статус по task ID из /api/v1/generate. Параметр model необязателен; task ID маршрутизируются автоматически, когда возможно.

cURL

curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

Ошибки

Ошибки используют тот же формат, что и успешные ответы. Публичные ответы не раскрывают внутренние имена провайдеров, worker или маршрутизацию.

JSON

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}

Статус	Значение
`400`	Отсутствуют или неверные параметры.
`401`	Отсутствует или неверный API-ключ.
`402`	Недостаточно кредитов.
`500`	Ошибка сервиса или сервера. Обратитесь в поддержку при повторении.