Images

Overview

The Images API allows you to generate images from text prompts, edit existing images, and create variations. All image generation requests flow through RedPill’s privacy-protected gateway.

All image generation requests are processed through TEE-protected infrastructure, ensuring your prompts and generated images remain confidential.

Supported Models

RedPill supports image generation models from multiple providers:

Model	Provider	Description	Max Resolution
`stability/stable-diffusion-3-5-large`	Stability AI	Latest SD 3.5 model	2048x2048
`stability/stable-diffusion-3-5-medium`	Stability AI	Faster SD 3.5	1536x1536
`stability/stable-diffusion-ultra`	Stability AI	Ultra-high quality	2048x2048
`recraft/recraft-v3`	Recraft AI	Brand-consistent generation	2048x2048
`recraft/recraft-v3-svg`	Recraft AI	Vector graphics generation	2048x2048
`openai/dall-e-3`	OpenAI	DALL-E 3	1024x1024
`segmind/sd3-turbo`	Segmind	Fast generation	1024x1024

List Image Models

Get all image models programmatically →

Generate Images

curl https://api.redpill.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REDPILL_API_KEY" \
  -d '{
    "model": "stability/stable-diffusion-3-5-large",
    "prompt": "A serene mountain landscape at sunset with aurora borealis",
    "n": 1,
    "size": "1024x1024",
    "quality": "standard",
    "response_format": "url"
  }'

{
  "created": 1704067200,
  "data": [
    {
      "url": "https://storage.redpill.ai/images/img-abc123xyz.png",
      "revised_prompt": "A serene mountain landscape at sunset with vibrant aurora borealis dancing in the sky"
    }
  ]
}

Request Parameters

model

string

required

The image generation model to use (e.g., stability/stable-diffusion-3-5-large)

prompt

string

required

A text description of the desired image. Maximum length varies by model (typically 1000-4000 characters).

integer

default:"1"

Number of images to generate. Must be between 1 and 10.

size

string

default:"1024x1024"

Image resolution. Supported sizes vary by model:

256x256
512x512
1024x1024
1536x1536
2048x2048

quality

string

default:"standard"

Image quality setting:

standard - Faster generation
hd - Higher quality (if supported by model)

response_format

string

default:"url"

Response format:

url - Returns URL to hosted image (valid for 1 hour)
b64_json - Returns base64-encoded image data

style

string

Style preset (model-specific):

vivid - More creative and dramatic
natural - More realistic and natural

Response Fields

created

integer

Unix timestamp of when the image was generated

data

array

Array of generated images

Show Image Object

url

string

URL to the generated image (available for 1 hour)

b64_json

string

Base64-encoded image data (only if response_format: "b64_json")

revised_prompt

string

The prompt after safety filters and model optimization

Edit Images

Edit portions of an existing image using a text prompt and mask.

Image editing is currently supported by DALL-E models only. Other providers may not support this endpoint.

curl https://api.redpill.ai/v1/images/edits \
  -H "Authorization: Bearer $REDPILL_API_KEY" \
  -F image="@original.png" \
  -F mask="@mask.png" \
  -F prompt="Add a rainbow in the sky" \
  -F model="openai/dall-e-3" \
  -F n=1 \
  -F size="1024x1024"

Request Parameters

model

string

required

The image editing model to use (e.g., openai/dall-e-3)

image

file

required

The image to edit. Must be a valid PNG file, less than 4MB, and square.

mask

file

Mask image indicating areas to edit. Transparent areas (alpha channel = 0) will be edited. Must be PNG, same size as original.

prompt

string

required

Description of the desired edits

integer

default:"1"

Number of edited images to generate (1-10)

size

string

default:"1024x1024"

Size of generated images (256x256, 512x512, or 1024x1024)

Create Variations

Generate variations of an existing image.

curl https://api.redpill.ai/v1/images/variations \
  -H "Authorization: Bearer $REDPILL_API_KEY" \
  -F image="@original.png" \
  -F model="openai/dall-e-3" \
  -F n=2 \
  -F size="1024x1024"

Request Parameters

model

string

required

The image model to use (e.g., openai/dall-e-3)

image

file

required

Source image for variations. Must be PNG, less than 4MB, and square.

integer

default:"1"

Number of variations to generate (1-10)

size

string

default:"1024x1024"

Size of generated variations

response_format

string

default:"url"

url - Returns image URLs
b64_json - Returns base64-encoded images

Privacy & Security

TEE-Protected Generation

All image generation requests flow through hardware-protected secure enclaves

Confidential Prompts

Your prompts are processed in isolated secure environments

Temporary Storage

Generated images are hosted for 1 hour, then automatically deleted

No Training Data

Your images are never used to train models

Best Practices

Prompt Engineering

Be Specific and Detailed

✅ Good: "A photorealistic portrait of a golden retriever puppy sitting on a red velvet cushion, soft natural lighting, shallow depth of field"

❌ Vague: "A dog"

Specify Style and Mood

✅ "Watercolor painting style, pastel colors, dreamy atmosphere"
✅ "Cinematic photography, golden hour lighting, dramatic composition"
✅ "Minimalist vector art, flat design, bright colors"

Include Technical Details

✅ "Shot on Canon EOS R5, 85mm f/1.4, bokeh background"
✅ "Octane render, 8K resolution, ray tracing"
✅ "Professional studio lighting, three-point lighting setup"

Use Negative Prompts (Model-Specific)

Some models support negative prompts to avoid unwanted elements:

{
  "prompt": "Beautiful landscape",
  "negative_prompt": "blur, distortion, low quality, watermark"
}

Cost Optimization

Start with Lower Resolution

Generate at 512x512 or 1024x1024 first, upscale later if needed

Use Appropriate Models

Fast iterations: Use turbo models (e.g., segmind/sd3-turbo)
Final quality: Use premium models (e.g., stability/stable-diffusion-ultra)

Generate Multiple Variations

Use n: 4 to get multiple options in a single request (more efficient than 4 separate requests)

Cache Generated Images

Download and store images you want to keep (URLs expire after 1 hour)

Error Handling

{
  "error": {
    "message": "Invalid size '512x1024'. Must be square (e.g., '1024x1024')",
    "type": "invalid_request_error",
    "param": "size",
    "code": 400
  }
}

Common Errors

Error Code	Description	Solution
400	Invalid parameters	Check size, model, and prompt parameters
400	Content policy violation	Revise prompt to comply with content policies
401	Authentication failed	Verify API key is correct
403	Insufficient credits	Add credits to your account
413	Image too large	Reduce image file size (< 4MB)
429	Rate limit exceeded	Implement exponential backoff
500	Server error	Retry with exponential backoff

Examples

Product Mockup

response = client.images.generate(
    model="stability/stable-diffusion-3-5-large",
    prompt="Professional product photography of a sleek wireless headphone, white background, studio lighting, 4K, commercial photography style",
    size="1024x1024",
    quality="hd"
)

Concept Art

response = client.images.generate(
    model="stability/stable-diffusion-ultra",
    prompt="Futuristic cyberpunk cityscape at night, neon lights, flying cars, towering skyscrapers, rain-soaked streets, blade runner aesthetic, highly detailed",
    size="2048x2048",
    quality="hd"
)

Logo Design

response = client.images.generate(
    model="recraft/recraft-v3-svg",
    prompt="Modern minimalist logo for a tech startup, geometric shapes, blue and white color scheme, professional, clean design",
    size="1024x1024"
)

Illustration

response = client.images.generate(
    model="stability/stable-diffusion-3-5-medium",
    prompt="Children's book illustration, friendly dragon reading a book under a tree, watercolor style, soft colors, whimsical, storybook art",
    size="1536x1536"
)

Next Steps

Vision Models

Use vision models to analyze generated images

Supported Models

Browse all available image generation models

Pricing

View image generation pricing

API Reference

Complete API documentation

Get Started

API Reference

Guides

Integrations

Use Cases

Overview

Supported Models

List Image Models

Generate Images

Request Parameters

Response Fields

Edit Images

Request Parameters

Create Variations

Request Parameters

Privacy & Security

TEE-Protected Generation

Confidential Prompts

Temporary Storage

No Training Data

Best Practices

Prompt Engineering

Cost Optimization

Error Handling

Common Errors

Examples

Product Mockup

Concept Art

Logo Design

Illustration

Next Steps

Vision Models

Supported Models

Pricing

API Reference

Get Started

API Reference

Guides

Integrations

Use Cases

​Overview

​Supported Models

List Image Models

​Generate Images

​Request Parameters

​Response Fields

​Edit Images

​Request Parameters

​Create Variations

​Request Parameters

​Privacy & Security

TEE-Protected Generation

Confidential Prompts

Temporary Storage

No Training Data

​Best Practices

​Prompt Engineering

​Cost Optimization

​Error Handling

​Common Errors

​Examples

​Product Mockup

​Concept Art

​Logo Design

​Illustration

​Next Steps

Vision Models

Supported Models

Pricing

API Reference

Overview

Supported Models

Generate Images

Request Parameters

Response Fields

Edit Images

Request Parameters

Create Variations

Request Parameters

Privacy & Security

Best Practices

Prompt Engineering

Cost Optimization

Error Handling

Common Errors

Examples

Product Mockup

Concept Art

Logo Design

Illustration

Next Steps