Endpoint
POST /v1/images/generations
Request
The AI provider to use (e.g., openai, stability-ai)
Your API key for the specified provider
Body Parameters
A text description of the desired image(s). Maximum length varies by model.
The model to use for image generation (e.g., dall-e-3, dall-e-2)
Number of images to generate (1-10 for DALL-E 2, only 1 for DALL-E 3)
Size of the generated images
- DALL-E 3:
1024x1024, 1024x1792, 1792x1024
- DALL-E 2:
256x256, 512x512, 1024x1024
Quality of the image: standard or hd (DALL-E 3 only)
Style of the generated images: vivid or natural (DALL-E 3 only)
Format of the response: url or b64_json
Unique identifier for the end-user
Response
Unix timestamp of when the image was created
Array of generated imagesURL of the generated image (when response_format is url)
Base64-encoded image data (when response_format is b64_json)
The prompt that was used to generate the image (DALL-E 3 may revise prompts)
Examples
Basic Image Generation
curl http://localhost:8787/v1/images/generations \
-H "Content-Type: application/json" \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-d '{
"prompt": "A cute baby sea otter wearing a beret",
"model": "dall-e-3",
"n": 1,
"size": "1024x1024"
}'
Response
{
"created": 1677652288,
"data": [
{
"url": "https://...",
"revised_prompt": "A charming young sea otter, its fur wet and sleek, wearing a classic French beret tilted at a jaunty angle..."
}
]
}
Python SDK
from portkey_ai import Portkey
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.generate(
prompt="A cute baby sea otter wearing a beret",
model="dall-e-3",
n=1,
size="1024x1024",
quality="hd"
)
image_url = response.data[0].url
print(f"Image URL: {image_url}")
print(f"Revised prompt: {response.data[0].revised_prompt}")
JavaScript SDK
import Portkey from 'portkey-ai';
const client = new Portkey({
provider: 'openai',
Authorization: 'sk-...'
});
const response = await client.images.generate({
prompt: 'A cute baby sea otter wearing a beret',
model: 'dall-e-3',
n: 1,
size: '1024x1024',
quality: 'hd'
});
const imageUrl = response.data[0].url;
console.log(`Image URL: ${imageUrl}`);
console.log(`Revised prompt: ${response.data[0].revised_prompt}`);
Generate Multiple Images (DALL-E 2)
curl http://localhost:8787/v1/images/generations \
-H "Content-Type: application/json" \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-d '{
"prompt": "A futuristic cityscape at sunset",
"model": "dall-e-2",
"n": 4,
"size": "512x512"
}'
Download and Save Image
from portkey_ai import Portkey
import requests
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.generate(
prompt="A serene mountain landscape",
model="dall-e-3"
)
image_url = response.data[0].url
# Download and save
image_data = requests.get(image_url).content
Path("generated_image.png").write_bytes(image_data)
print("Image saved as generated_image.png")
from portkey_ai import Portkey
import base64
from pathlib import Path
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.generate(
prompt="A magical forest with glowing mushrooms",
model="dall-e-3",
response_format="b64_json"
)
# Decode and save base64 image
image_data = base64.b64decode(response.data[0].b64_json)
Path("image.png").write_bytes(image_data)
HD Quality with Natural Style
curl http://localhost:8787/v1/images/generations \
-H "Content-Type: application/json" \
-H "x-portkey-provider: openai" \
-H "x-portkey-api-key: sk-..." \
-d '{
"prompt": "A professional photograph of a coffee cup on a wooden table",
"model": "dall-e-3",
"size": "1024x1024",
"quality": "hd",
"style": "natural"
}'
Landscape Orientation
from portkey_ai import Portkey
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.generate(
prompt="A panoramic view of the Grand Canyon at sunrise",
model="dall-e-3",
size="1792x1024", # Landscape format
quality="hd"
)
print(response.data[0].url)
Portrait Orientation
from portkey_ai import Portkey
client = Portkey(
provider="openai",
Authorization="sk-..."
)
response = client.images.generate(
prompt="A portrait of a wise old wizard",
model="dall-e-3",
size="1024x1792", # Portrait format
quality="hd"
)
print(response.data[0].url)
Prompt Engineering Tips
- Be Specific: Include details about subject, style, lighting, and composition
- Mention Style: Specify artistic styles (e.g., “oil painting”, “3D render”, “photograph”)
- Describe Details: Include colors, textures, and atmosphere
- Set the Scene: Describe the environment and context
Example Prompts
# Detailed and specific
"A photorealistic close-up of a vintage typewriter on an oak desk, soft natural lighting from a window, shallow depth of field, golden hour ambiance"
# Artistic style
"An impressionist painting of a Parisian café in autumn, warm colors, loose brushstrokes, people sitting at outdoor tables"
# 3D render
"A futuristic sports car, sleek metallic blue finish, studio lighting, 3D render, high detail, reflective surfaces"
Rate Limits
Rate limits vary by provider and tier:
- DALL-E 3: Typically 5-50 images per minute depending on tier
- DALL-E 2: Higher throughput, up to 50 images per minute
Content Policy
All generated images must comply with provider content policies. Requests that violate policies will be rejected.