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": "dall-e-3",
  "provider": "openai",
  "type": "image",
  "size": "1024x1024",
  "quality": "standard",
  "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 | standard | standard or hd | | style | string | — | Style hint when supported (e.g. DALL·E 3) |

Size options

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

Quality & style

Parameter	Values	Notes
quality	standard, hd	HD costs more and takes longer
style	vivid, natural	Vivid is more dramatic; natural is subtler

Success response

{
  "success": true,
  "data": {
    "image_url": "https://example.com/generated-image.png",
    "model": "dall-e-3",
    "provider": "openai",
    "tokens_used": 2000,
    "cost": 0.04,
    "remaining_tokens": 8000,
    "usage_percentage": "20.0"
  }
}

Download or persist image_url promptly — provider URLs may expire.

Example prompts

Artistic style

{
  "prompt": "A serene Japanese garden with cherry blossoms, oil painting style",
  "model": "dall-e-3",
  "provider": "openai",
  "type": "image",
  "size": "1792x1024",
  "quality": "hd",
  "style": "vivid"
}

Product photography

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

Logo concept

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

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.