JoyAI Image API

API Documentation

Generate and edit images with one public API surface. Use joyai for instruction-based image editing, or gptimage2 for GPT Image 2 text-to-image and image editing.

Manage API Keys Quick Start

Overview

Endpoint

/api/v1/generate

One endpoint for supported image models. Select behavior with the model field.

Auth

Bearer API keys

Use a dashboard API key in the Authorization header. Server-side keys are never sent to browsers.

Async

Task-based results

Generation returns a task ID. Poll the status endpoint for final image URLs.

Authentication

Every request requires an API key in the Authorization header. Create or rotate keys from Dashboard > API Keys.

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Models and Credits

model	Best for	Required image input	Credits
`joyai`	Instruction-based image editing with 1 to 3 reference images.	Yes, 1 to 3 image URLs.	24 credits per request.
`gptimage2`	Text-to-image and image editing with GPT Image 2.	Optional. Add images for edit mode.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high for 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high for 1k/2k/4k.

Quick Start

Send a request to POST /api/v1/generate. The API returns a task ID immediately; use GET /api/v1/status to poll until the task succeeds or fails.

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

Creates an image generation or image editing task. The request body is JSON.

Request Parameters

Name	Type	Required	Description
`model`	string	Yes	Use joyai or gptimage2.
`prompt`	string	Yes	Natural-language instruction. joyai allows up to 1500 characters; gptimage2 allows up to 20000 characters.
`images`	string[]	Required for joyai; optional for gptimage2	Image URLs. joyai accepts 1 to 3 images. gptimage2 switches to edit mode when images are present.
`size`	string	Optional for joyai	Output size such as 10241024. Defaults to 10241024.
`quality`	string	Optional for gptimage2	low, medium, or high. Defaults to medium.
`resolution`	string	Optional for gptimage2	1k, 2k, or 4k. Defaults to 1k.
`aspect_ratio`	string	Optional for gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, or 21:9.
`output_format`	string	Optional for gptimage2	png, jpeg, or webp. Defaults to png.
`callback_url`	string	Optional	A URL that can be stored with the task for downstream callback workflows.

JoyAI Edit Example

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 Example

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"
  }'

Response

JSON

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

GET /api/v1/status

Poll task status with the task ID returned by /api/v1/generate. The model parameter is optional; task IDs are routed automatically when possible.

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"
  }
}

Errors

Errors use the same envelope as successful responses. The API does not expose internal provider names, worker names, or routing details in public responses.

JSON

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

Status	Meaning
`400`	Missing or invalid request parameters.
`401`	Missing or invalid API key.
`402`	Insufficient credits.
`500`	Generation service or server error. Contact support if it repeats.