Image Studio API Reference¶

Complete API documentation for Image Studio, including all endpoints, request/response models, authentication, and usage examples.

Base URL¶

All Image Studio endpoints are prefixed with /api/image-studio

Authentication¶

All endpoints require authentication via Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

The token is obtained through the standard ALwrity authentication flow. See Authentication Guide for details.

API Architecture¶

graph TB
    Client[Client Application] --> API[Image Studio API]

    API --> Create[Create Studio]
    API --> Edit[Edit Studio]
    API --> Upscale[Upscale Studio]
    API --> Control[Control Studio]
    API --> Social[Social Optimizer]
    API --> Templates[Templates]
    API --> Providers[Providers]

    Create --> Manager[ImageStudioManager]
    Edit --> Manager
    Upscale --> Manager
    Control --> Manager
    Social --> Manager

    Manager --> Stability[Stability AI]
    Manager --> WaveSpeed[WaveSpeed AI]
    Manager --> HuggingFace[HuggingFace]
    Manager --> Gemini[Gemini]

    style Client fill:#e3f2fd
    style API fill:#e1f5fe
    style Manager fill:#f3e5f5

Endpoint Categories¶

Create Studio Endpoints¶

Generate Image¶

Generate one or more images from text prompts.

Endpoint: POST /api/image-studio/create

Request Body:

{
  "prompt": "Modern minimalist workspace with laptop",
  "template_id": "linkedin_post",
  "provider": "auto",
  "model": null,
  "width": null,
  "height": null,
  "aspect_ratio": null,
  "style_preset": "photographic",
  "quality": "standard",
  "negative_prompt": "blurry, low quality",
  "guidance_scale": null,
  "steps": null,
  "seed": null,
  "num_variations": 1,
  "enhance_prompt": true,
  "use_persona": false,
  "persona_id": null
}

Request Fields:

Field	Type	Required	Description
`prompt`	string	Yes	Image generation prompt
`template_id`	string	No	Template ID to use
`provider`	string	No	Provider: auto, stability, wavespeed, huggingface, gemini
`model`	string	No	Specific model to use
`width`	integer	No	Image width in pixels
`height`	integer	No	Image height in pixels
`aspect_ratio`	string	No	Aspect ratio (e.g., '1:1', '16:9')
`style_preset`	string	No	Style preset
`quality`	string	No	Quality: draft, standard, premium (default: standard)
`negative_prompt`	string	No	Negative prompt
`guidance_scale`	float	No	Guidance scale
`steps`	integer	No	Number of inference steps
`seed`	integer	No	Random seed
`num_variations`	integer	No	Number of variations (1-10, default: 1)
`enhance_prompt`	boolean	No	Enhance prompt with AI (default: true)
`use_persona`	boolean	No	Use persona for brand consistency (default: false)
`persona_id`	string	No	Persona ID

Response:

{
  "success": true,
  "request": {
    "prompt": "Modern minimalist workspace with laptop",
    "enhanced_prompt": "Modern minimalist workspace with laptop, professional photography, high quality",
    "template_id": "linkedin_post",
    "template_name": "LinkedIn Post",
    "provider": "wavespeed",
    "model": "ideogram-v3-turbo",
    "dimensions": "1200x628",
    "quality": "standard"
  },
  "results": [
    {
      "image_base64": "iVBORw0KGgoAAAANS...",
      "width": 1200,
      "height": 628,
      "provider": "wavespeed",
      "model": "ideogram-v3-turbo",
      "variation": 1
    }
  ],
  "total_generated": 1,
  "total_failed": 0
}

Response Fields:

Field	Type	Description
`success`	boolean	Operation success status
`request`	object	Request details with applied settings
`results`	array	Generated images with base64 data
`total_generated`	integer	Number of successfully generated images
`total_failed`	integer	Number of failed generations

Error Responses:

400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
500 Internal Server Error: Generation failed

Get Templates¶

Get available image templates, optionally filtered by platform or category.

Endpoint: GET /api/image-studio/templates

Query Parameters:

Parameter	Type	Required	Description
`platform`	string	No	Filter by platform (instagram, facebook, twitter, etc.)
`category`	string	No	Filter by category (social_media, blog_content, etc.)

Example Request:

GET /api/image-studio/templates?platform=instagram

Response:

{
  "templates": [
    {
      "id": "instagram_feed_square",
      "name": "Instagram Feed Post (Square)",
      "category": "social_media",
      "platform": "instagram",
      "aspect_ratio": {
        "ratio": "1:1",
        "width": 1080,
        "height": 1080,
        "label": "Square"
      },
      "description": "Perfect for Instagram feed posts",
      "recommended_provider": "ideogram",
      "style_preset": "photographic",
      "quality": "premium",
      "use_cases": ["Product showcase", "Lifestyle posts", "Brand content"]
    }
  ],
  "total": 4
}

Search Templates¶

Search templates by query string.

Endpoint: GET /api/image-studio/templates/search

Query Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Search query

Example Request:

GET /api/image-studio/templates/search?query=linkedin

Response: Same format as Get Templates

Get template recommendations based on use case.

Endpoint: GET /api/image-studio/templates/recommend

Query Parameters:

Parameter	Type	Required	Description
`use_case`	string	Yes	Use case description
`platform`	string	No	Optional platform filter

Example Request:

GET /api/image-studio/templates/recommend?use_case=product+showcase&platform=instagram

Response: Same format as Get Templates

Get Providers¶

Get available AI providers and their capabilities.

Endpoint: GET /api/image-studio/providers

Response:

{
  "providers": {
    "stability": {
      "name": "Stability AI",
      "models": ["ultra", "core", "sd3.5-large"],
      "capabilities": ["generation", "editing", "upscaling"],
      "max_resolution": "2048x2048",
      "cost_range": "3-8 credits"
    },
    "wavespeed": {
      "name": "WaveSpeed AI",
      "models": ["ideogram-v3-turbo", "qwen-image"],
      "capabilities": ["generation"],
      "max_resolution": "1024x1024",
      "cost_range": "1-6 credits"
    }
  }
}

Estimate Cost¶

Estimate cost for image generation operations.

Endpoint: POST /api/image-studio/estimate-cost

Request Body:

{
  "provider": "wavespeed",
  "model": "ideogram-v3-turbo",
  "operation": "generate",
  "num_images": 1,
  "width": 1200,
  "height": 628
}

Request Fields:

Field	Type	Required	Description
`provider`	string	Yes	Provider name
`model`	string	No	Model name
`operation`	string	No	Operation type (default: generate)
`num_images`	integer	No	Number of images (default: 1)
`width`	integer	No	Image width
`height`	integer	No	Image height

Response:

{
  "estimated_cost": 5,
  "currency": "credits",
  "provider": "wavespeed",
  "model": "ideogram-v3-turbo",
  "operation": "generate",
  "num_images": 1
}

Edit Studio Endpoints¶

Process Edit¶

Perform Edit Studio operations on images.

Endpoint: POST /api/image-studio/edit/process

Request Body:

{
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "operation": "remove_background",
  "prompt": null,
  "negative_prompt": null,
  "mask_base64": null,
  "search_prompt": null,
  "select_prompt": null,
  "background_image_base64": null,
  "lighting_image_base64": null,
  "expand_left": 0,
  "expand_right": 0,
  "expand_up": 0,
  "expand_down": 0,
  "provider": null,
  "model": null,
  "style_preset": null,
  "guidance_scale": null,
  "steps": null,
  "seed": null,
  "output_format": "png",
  "options": {}
}

Request Fields:

Field	Type	Required	Description
`image_base64`	string	Yes	Primary image (base64 or data URL)
`operation`	string	Yes	Operation: remove_background, inpaint, outpaint, search_replace, search_recolor, general_edit
`prompt`	string	No	Primary prompt/instruction
`negative_prompt`	string	No	Negative prompt
`mask_base64`	string	No	Optional mask image (base64)
`search_prompt`	string	No	Search prompt for replace operations
`select_prompt`	string	No	Select prompt for recolor operations
`background_image_base64`	string	No	Reference background image
`lighting_image_base64`	string	No	Reference lighting image
`expand_left`	integer	No	Outpaint expansion left (pixels)
`expand_right`	integer	No	Outpaint expansion right (pixels)
`expand_up`	integer	No	Outpaint expansion up (pixels)
`expand_down`	integer	No	Outpaint expansion down (pixels)
`provider`	string	No	Explicit provider override
`model`	string	No	Explicit model override
`style_preset`	string	No	Style preset
`guidance_scale`	float	No	Guidance scale
`steps`	integer	No	Inference steps
`seed`	integer	No	Random seed
`output_format`	string	No	Output format (default: png)
`options`	object	No	Advanced provider-specific options

Response:

{
  "success": true,
  "operation": "remove_background",
  "provider": "stability",
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "width": 1200,
  "height": 628,
  "metadata": {
    "operation": "remove_background",
    "processing_time": 2.5
  }
}

Get Edit Operations¶

Get metadata for all available Edit Studio operations.

Endpoint: GET /api/image-studio/edit/operations

Response:

{
  "operations": {
    "remove_background": {
      "label": "Remove Background",
      "description": "Isolate the main subject",
      "provider": "stability",
      "fields": {
        "prompt": false,
        "mask": false,
        "negative_prompt": false,
        "search_prompt": false,
        "select_prompt": false,
        "background": false,
        "lighting": false,
        "expansion": false
      }
    },
    "inpaint": {
      "label": "Inpaint & Fix",
      "description": "Edit specific regions using prompts and optional masks",
      "provider": "stability",
      "fields": {
        "prompt": true,
        "mask": true,
        "negative_prompt": true,
        "search_prompt": false,
        "select_prompt": false,
        "background": false,
        "lighting": false,
        "expansion": false
      }
    }
  }
}

Upscale Studio Endpoints¶

Upscale Image¶

Upscale an image using AI-powered upscaling.

Endpoint: POST /api/image-studio/upscale

Request Body:

{
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "mode": "conservative",
  "target_width": null,
  "target_height": null,
  "preset": "print",
  "prompt": "High fidelity upscale preserving original details"
}

Request Fields:

Field	Type	Required	Description
`image_base64`	string	Yes	Image to upscale (base64 or data URL)
`mode`	string	No	Mode: fast, conservative, creative, auto (default: auto)
`target_width`	integer	No	Target width in pixels
`target_height`	integer	No	Target height in pixels
`preset`	string	No	Named preset: web, print, social
`prompt`	string	No	Prompt for conservative/creative modes

Response:

{
  "success": true,
  "mode": "conservative",
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "width": 3072,
  "height": 2048,
  "metadata": {
    "preset": "print",
    "original_width": 768,
    "original_height": 512,
    "upscale_factor": 4.0
  }
}

Control Studio Endpoints¶

Process Control¶

Perform Control Studio operations (sketch-to-image, style transfer, etc.).

Endpoint: POST /api/image-studio/control/process

Request Body:

{
  "control_image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "operation": "sketch",
  "prompt": "Modern office interior",
  "style_image_base64": null,
  "negative_prompt": null,
  "control_strength": 0.8,
  "fidelity": null,
  "style_strength": null,
  "composition_fidelity": null,
  "change_strength": null,
  "aspect_ratio": null,
  "style_preset": null,
  "seed": null,
  "output_format": "png"
}

Request Fields:

Field	Type	Required	Description
`control_image_base64`	string	Yes	Control image (sketch/structure/style)
`operation`	string	Yes	Operation: sketch, structure, style, style_transfer
`prompt`	string	Yes	Text prompt for generation
`style_image_base64`	string	No	Style reference image (for style_transfer)
`negative_prompt`	string	No	Negative prompt
`control_strength`	float	No	Control strength 0.0-1.0 (for sketch/structure)
`fidelity`	float	No	Style fidelity 0.0-1.0 (for style operation)
`style_strength`	float	No	Style strength 0.0-1.0 (for style_transfer)
`composition_fidelity`	float	No	Composition fidelity 0.0-1.0 (for style_transfer)
`change_strength`	float	No	Change strength 0.0-1.0 (for style_transfer)
`aspect_ratio`	string	No	Aspect ratio (for style operation)
`style_preset`	string	No	Style preset
`seed`	integer	No	Random seed
`output_format`	string	No	Output format (default: png)

Response:

{
  "success": true,
  "operation": "sketch",
  "provider": "stability",
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "width": 1024,
  "height": 1024,
  "metadata": {
    "operation": "sketch",
    "control_strength": 0.8
  }
}

Get Control Operations¶

Get metadata for all available Control Studio operations.

Endpoint: GET /api/image-studio/control/operations

Response: Similar format to Edit Operations

Optimize an image for multiple social media platforms.

Endpoint: POST /api/image-studio/social/optimize

Request Body:

{
  "image_base64": "data:image/png;base64,iVBORw0KGgo...",
  "platforms": ["instagram", "facebook", "linkedin"],
  "format_names": {
    "instagram": "Feed Post (Square)",
    "facebook": "Feed Post",
    "linkedin": "Post"
  },
  "show_safe_zones": false,
  "crop_mode": "smart",
  "focal_point": null,
  "output_format": "png"
}

Request Fields:

Field	Type	Required	Description
`image_base64`	string	Yes	Source image (base64 or data URL)
`platforms`	array	Yes	List of platforms to optimize for
`format_names`	object	No	Specific format per platform
`show_safe_zones`	boolean	No	Include safe zone overlay (default: false)
`crop_mode`	string	No	Crop mode: smart, center, fit (default: smart)
`focal_point`	object	No	Focal point for smart crop (x, y as 0-1)
`output_format`	string	No	Output format: png or jpg (default: png)

Response:

{
  "success": true,
  "results": [
    {
      "platform": "instagram",
      "format": "Feed Post (Square)",
      "image_base64": "data:image/png;base64,iVBORw0KGgo...",
      "width": 1080,
      "height": 1080
    },
    {
      "platform": "facebook",
      "format": "Feed Post",
      "image_base64": "data:image/png;base64,iVBORw0KGgo...",
      "width": 1200,
      "height": 630
    }
  ],
  "total_optimized": 2
}

Get Platform Formats¶

Get available formats for a specific social media platform.

Endpoint: GET /api/image-studio/social/platforms/{platform}/formats

Path Parameters:

Parameter	Type	Required	Description
`platform`	string	Yes	Platform name (instagram, facebook, etc.)

Response:

{
  "formats": [
    {
      "name": "Feed Post (Square)",
      "width": 1080,
      "height": 1080,
      "ratio": "1:1",
      "safe_zone": {
        "top": 0.15,
        "bottom": 0.15,
        "left": 0.1,
        "right": 0.1
      },
      "file_type": "PNG",
      "max_size_mb": 5.0
    }
  ]
}

Platform Specifications Endpoints¶

Get Platform Specs¶

Get specifications and requirements for a specific platform.

Endpoint: GET /api/image-studio/platform-specs/{platform}

Path Parameters:

Parameter	Type	Required	Description
`platform`	string	Yes	Platform name

Response:

{
  "name": "Instagram",
  "formats": [
    {
      "name": "Feed Post (Square)",
      "ratio": "1:1",
      "size": "1080x1080"
    }
  ],
  "file_types": ["JPG", "PNG"],
  "max_file_size": "30MB"
}

Health Check¶

Check Image Studio service health.

Endpoint: GET /api/image-studio/health

Response:

{
  "status": "healthy",
  "service": "image_studio",
  "version": "1.0.0",
  "modules": {
    "create_studio": "available",
    "templates": "available",
    "providers": "available"
  }
}

Error Handling¶

Error Response Format¶

All errors follow this format:

{
  "detail": "Error message description"
}

HTTP Status Codes¶

200 OK: Successful request
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
404 Not Found: Resource not found
500 Internal Server Error: Server error

Common Error Scenarios¶

Invalid Image Format:

{
  "detail": "Invalid base64 image payload"
}

Missing Required Field:

{
  "detail": "Prompt is required for inpainting"
}

Provider Error:

{
  "detail": "Image generation failed: Provider error message"
}

Authentication Error:

{
  "detail": "Authenticated user required for image operations."
}

Rate Limiting¶

Image Studio API follows standard ALwrity rate limiting:

Rate Limits: Based on subscription tier
Headers: Rate limit information in response headers
Retry: Use exponential backoff for rate limit errors

See Rate Limiting Guide for details.

Best Practices¶

Image Encoding¶

Base64 Format: All images should be base64 encoded
Data URLs: Support for data:image/png;base64,... format
Size Limits: Recommended under 10MB for best performance
Format: PNG or JPG supported

Request Optimization¶

Use Templates: Templates optimize settings automatically
Batch Operations: Generate multiple variations in one request
Estimate Costs: Use cost estimation before large operations
Error Handling: Implement retry logic for transient errors

Response Handling¶

Base64 Images: Decode base64 images in responses
Metadata: Use metadata for tracking and organization
Error Messages: Display user-friendly error messages
Progress: For long operations, implement polling if needed

Code Examples¶

Python Example¶

import requests
import base64

# Generate Image
url = "https://api.alwrity.com/api/image-studio/create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "prompt": "Modern office workspace",
    "template_id": "linkedin_post",
    "quality": "standard"
}
response = requests.post(url, json=data, headers=headers)
result = response.json()

# Decode image
image_data = base64.b64decode(result["results"][0]["image_base64"])
with open("generated_image.png", "wb") as f:
    f.write(image_data)

JavaScript Example¶

// Generate Image
const response = await fetch('https://api.alwrity.com/api/image-studio/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Modern office workspace',
    template_id: 'linkedin_post',
    quality: 'standard'
  })
});

const result = await response.json();

// Display image
const img = document.createElement('img');
img.src = `data:image/png;base64,${result.results[0].image_base64}`;
document.body.appendChild(img);

cURL Example¶

curl -X POST https://api.alwrity.com/api/image-studio/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Modern office workspace",
    "template_id": "linkedin_post",
    "quality": "standard"
  }'

Create Studio Guide - User guide for image generation
Edit Studio Guide - User guide for image editing
Upscale Studio Guide - User guide for upscaling
Social Optimizer Guide - User guide for social optimization
Providers Guide - Provider selection guide
Cost Guide - Cost management guide
Implementation Overview - Technical architecture

For authentication details, see the API Authentication Guide. For rate limiting, see the Rate Limiting Guide.

Image Studio API Reference¶

Base URL¶

Authentication¶

API Architecture¶

Endpoint Categories¶

Create Studio¶

Edit Studio¶

Upscale Studio¶

Control Studio¶

Social Optimizer¶

Platform Specifications¶

Health Check¶

Create Studio Endpoints¶

Generate Image¶

Get Templates¶

Search Templates¶

Recommend Templates¶

Get Providers¶

Estimate Cost¶

Edit Studio Endpoints¶

Process Edit¶

Get Edit Operations¶

Upscale Studio Endpoints¶

Upscale Image¶

Control Studio Endpoints¶

Process Control¶

Get Control Operations¶

Social Optimizer Endpoints¶

Optimize for Social¶

Get Platform Formats¶

Platform Specifications Endpoints¶

Get Platform Specs¶

Health Check¶

Health Check¶

Error Handling¶

Error Response Format¶

HTTP Status Codes¶

Common Error Scenarios¶

Rate Limiting¶

Best Practices¶

Image Encoding¶

Request Optimization¶

Response Handling¶

Code Examples¶

Python Example¶

JavaScript Example¶

cURL Example¶

Related Documentation¶