Generate Images

POST /v1/images/generations - Generate images from text prompts

Endpoint

POST /v1/images/generations

Creates an image based on a text prompt.

Request

Headers

Content-Type · string · required

Must be application/json

x-portkey-provider · string · required

The AI provider to use (e.g., openai, stability-ai)

x-portkey-api-key · string · required

Your API key for the specified provider

Body Parameters

prompt · string · required

A text description of the desired image(s). Maximum length varies by model.

model · string

The model to use for image generation (e.g., dall-e-3, dall-e-2)

n · integer · default: 1

Number of images to generate (1-10 for DALL-E 2, only 1 for DALL-E 3)

size · string

Size of the generated images

• DALL-E 3: 1024x1024, 1024x1792, 1792x1024
• DALL-E 2: 256x256, 512x512, 1024x1024

quality · string · default: "standard"

Quality of the image: standard or hd (DALL-E 3 only)

style · string · default: "vivid"

Style of the generated images: vivid or natural (DALL-E 3 only)

response_format · string · default: "url"

Format of the response: url or b64_json

user · string

Unique identifier for the end-user

Response

created · integer

Unix timestamp of when the image was created

data · array

Array of generated images

url · string

URL of the generated image (when response_format is url)

b64_json · string

Base64-encoded image data (when response_format is b64_json)

revised_prompt · string

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")

Base64 Response Format

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

1. Be Specific: Include details about subject, style, lighting, and composition
2. Mention Style: Specify artistic styles (e.g., “oil painting”, “3D render”, “photograph”)
3. Describe Details: Include colors, textures, and atmosphere
4. 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.