Files

Kunthawat Greethong c35fa52117 Base code

2026-01-08 22:39:53 +07:00

22 KiB

Raw Permalink Blame History

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.

22 KiB Raw Permalink Blame History

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

22 KiB

Raw Permalink Blame History