Skip to main content
Base URL: https://platform.runblob.io

​
POST /v1/chatgpt-images/generate

Creates an image generation task from text description using ChatGPT Image 1.5 model.
​
prompt
string
required
Text description of the image (1-4000 characters)
​
aspect_ratio
string
Image aspect ratio. Options: 1:1 (square), 4:3 (landscape), 3:4 (portrait)Optional — if not provided, model automatically chooses the best ratio for your prompt.
​
images
array
Array of up to 4 images for reference-based generation. Each element can be:
  • HTTP/HTTPS URL (e.g., "https://example.com/image.jpg")
  • Base64 with MIME type (e.g., "data:image/jpeg;base64,/9j/4AAQSkZJRg...")
  • Base64 without prefix (decoded as JPEG by default)
​
callback_url
string
Webhook URL for completion notifications
Aspect Ratio: Optional parameter. If omitted, model automatically selects the best ratio for your prompt.
curl -X POST https://platform.runblob.io/v1/chatgpt-images/generate -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{
  "prompt": "A futuristic city with flying cars, neon lights, cyberpunk style"
}'

​
Response

{
  "task_uuid": "dc62d83d-1953-4bca-8554-222679a7a4a9",
  "status": "pending",
  "price": "0.0123"
}
​
task_uuid
string
UUID of the generation task for status checking
​
status
string
Initial status, always "pending"
​
price
string
Amount charged in USD
Image generation typically takes 1-3 minutes. Use the task_uuid to check status or set up webhooks for notifications.Check status: GET /v1/chatgpt-images/generations/{task_uuid}

​
Generation Modes

The API supports 2 generation modes:

​
1. Text-to-Image

Generate image from text prompt only (no reference images). 
{
  "prompt": "A futuristic cyberpunk city with neon lights"
}

​
2. Reference-Based Generation

Generate image using up to 4 reference images.
  • Max images: 4 per request
  • Formats: JPEG, PNG, WEBP
  • Image sources:
    • HTTP/HTTPS URLs (server saves as link)
    • Base64 with MIME type: data:image/jpeg;base64,...
    • Base64 without prefix (decoded as JPEG)
{
  "prompt": "Combine these images into a beautiful collage",
  "images": [
    "https://example.com/ref1.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "/9j/4AAQSkZJRg..."  // Base64 without prefix
  ]
}

​
Image Format Options

HTTP/HTTPS URLs:
  • Server saves as link (doesn’t download)
  • Must be publicly accessible
  • Example: "https://example.com/image.jpg"
Full Base64 string:
  • Includes MIME type prefix
  • Example: "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  • Example: "data:image/png;base64,iVBORw0KGgoAAAANS..."
Plain Base64:
  • No prefix, decoded as JPEG by default
  • Example: "/9j/4AAQSkZJRg..."
  • Automatically uploaded to S3

​
Error Responses

400 Bad Request: 
{
  "detail": "Validation error: images format invalid"
}
402 Payment Required: 
{
  "detail": "INSUFFICIENT_CREDITS"
}
500 Internal Server Error: 
{
  "detail": "OPENAI_DECLINED"
}
503 Service Unavailable: 
{
  "detail": "Maintenance"
}