Image Generation

Create images by setting type: "image" on the same External API endpoint.

Request

POST /api/external/ai
Content-Type: application/json
X-API-Key: your-api-key-here

{
  "prompt": "A futuristic cityscape with flying cars at sunset",
  "model": "gpt-image-2",
  "provider": "openai",
  "type": "image",
  "size": "1024x1024",
  "quality": "medium",
  "style": "vivid"
}

Parameters

| Parameter | Type | Default | Description | | — | — | — | | prompt | string | — | Required. Image description | | model | string | — | Required. Image-capable model | | provider | string | deepseek | Must support image generation | | type | string | — | Must be "image" | | size | string | 1024x1024 | Output dimensions | | quality | string | medium | low, medium, or high (legacy: standard→medium, hd→high) | | style | string | — | Style hint when supported |

Size options

Value	Orientation
1024x1024	Square (default)
1792x1024	Landscape
1024x1792	Portrait

Note: 256x256 / 512x512 are below gpt-image-2’s minimum pixel count and will be rejected by the provider.

Quality & style

Parameter	Values	Notes
quality	low, medium, high	Billing scales vs medium (~0.12× / 1× / 4×). Legacy standard/hd still accepted.
style	vivid, natural	Vivid is more dramatic; natural is subtler

GPT Image models return base64 image data. The API uploads it and returns a hosted image_url when possible (otherwise a data: URL).

Success response

{
  "success": true,
  "data": {
    "image_url": "https://example.com/generated-image.png",
    "quality": "medium",
    "model": "gpt-image-2",
    "provider": "openai",
    "tokens_used": 2000,
    "remaining_tokens": 8000,
    "usage_percentage": "20.0"
  }
}

Download or persist image_url promptly — temporary URLs may expire.

Example prompts

Artistic style

{
  "prompt": "A serene Japanese garden with cherry blossoms, oil painting style",
  "model": "gpt-image-2",
  "provider": "openai",
  "type": "image",
  "size": "1792x1024",
  "quality": "high",
  "style": "vivid"
}

Product photography

{
  "prompt": "Professional product shot of a modern smartwatch on a clean white background, studio lighting",
  "model": "gpt-image-2",
  "provider": "openai",
  "type": "image",
  "size": "1024x1024",
  "quality": "high",
  "style": "natural"
}

Logo concept

{
  "prompt": "Minimalist logo design for a tech startup, geometric shapes, blue and white color scheme",
  "model": "gpt-image-2",
  "provider": "openai",
  "type": "image",
  "size": "1024x1024",
  "quality": "medium"
}

Common failures

Error	Status	Cause
Provider does not support image generation	400	Wrong provider for type: "image"
Insufficient tokens	402	Not enough balance
Model not found	400	Invalid model id/name
Provider/model not allowed	403	API key restrictions

Call GET /api/external/ai and inspect image_generation_providers to see which models your account can use.