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": "openai/gpt-image-1-mini",
  "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	model’s provider	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 openai/gpt-image-1-mini’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": "openai/gpt-image-1-mini",
    "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": "openai/gpt-image-1-mini",
  "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": "openai/gpt-image-1-mini",
  "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": "openai/gpt-image-1-mini",
  "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.

OpenAI SDK compatibility

POST /v1/images/generations supports model, prompt, size, quality, style, n: 1, and response_format: "url" | "b64_json".

const image = await client.images.generate({
  model: "your-image-model",
  prompt: "A refined product photograph on a warm neutral background",
  size: "1024x1024",
  response_format: "b64_json",
});

Image edits, masks, and variations are separate operations and are not exposed by the current public API.