Skip to main content
POST
Create Generation V2
Create a new AI-powered image generation request. Upload 1-5 example images and provide instructions to generate new images based on your examples. Uses Replicate AI’s Stability AI SDXL model for high-quality results.

Authentication

Requires valid JWT token with end_user role and project-scoped headers.

Headers

Authorization
string
required
Bearer JWT access token obtained from login
X-User-Role
string
required
Must be set to end_user
X-Developer-Key
string
required
Developer key associated with the project
X-Project-ID
string
required
Project UUID for project-scoped access
X-API-Key
string
required
Project API key for authentication
Content-Type
string
required
Must be multipart/form-data for file uploads

Request Body (Multipart Form Data)

example_images
file[]
required
Array of 1-5 example images to guide generation. Supported formats: JPEG, PNG, WebP. Maximum 10MB per image.
instructions
json string
required
JSON-encoded string containing generation instructions. Must be between 1-1000 characters when serialized.Example: {"prompt": "Generate a futuristic cityscape with neon lights"}

Response

id
string
Unique UUID identifier for the generation request
status
string
Initial status: always pending for new requests
message
string
Confirmation message: “Generation request submitted successfully”

Example Request

Example Response

Generation Status Lifecycle

After submission, the generation progresses through multiple states:
  1. pending - Request queued for processing
  2. processing - AI model actively generating image
  3. completed - Generation successful, image available
  4. failed - Generation failed due to error
Check status using the Get Generation Status endpoint. (((REPLACE_THIS_WITH_IMAGE: cloud-api-generation-lifecycle-diagram.png: Flowchart showing generation states from pending through processing to completed or failed with example durations)))

Image Requirements

File Formats

  • Supported: JPEG (.jpg, .jpeg), PNG (.png), WebP (.webp)
  • Unsupported: GIF, TIFF, BMP, SVG

File Size

  • Maximum per image: 10MB
  • Total request size: 50MB (5 images × 10MB each)

Image Count

  • Minimum: 1 example image required
  • Maximum: 5 example images allowed
  • Recommended: 3-5 images for best results

Image Quality

For best generation results:
  • Use high-resolution images (1024x1024 or higher)
  • Ensure images are well-lit and in focus
  • Provide diverse examples showing different angles/styles
  • Avoid heavily compressed or low-quality images

Instructions Format

The instructions field must be a JSON-encoded string with the following constraints: Structure:
Constraints:
  • Must be valid JSON
  • Serialized length: 1-1000 characters
  • Must contain at least a prompt key
  • Other keys are optional and passed to AI model
Example Valid Instructions:

Processing Time

Typical generation times:
  • Fast: 1-2 minutes (simple generations)
  • Average: 2-5 minutes (standard complexity)
  • Slow: 5-10 minutes (complex or high-detail generations)
Poll the Generation Status endpoint every 10-15 seconds to check for completion. Avoid polling more frequently to minimize API usage.

Use Cases

Portfolio Website

Generate custom images for your portfolio projects:

E-Commerce Product Variations

Create product variations for online stores:

Content Creation Platform

Build a content creation tool with AI generation:

Error Responses

Missing Example Images (422)

Too Many Images (422)

File Too Large (413)

Invalid File Format (422)

Invalid Instructions (422)

Instructions Too Long (422)

Unauthorized (401)

Insufficient Permissions (403)

Rate Limit Exceeded (429)

Rate Limits

AI generation endpoints have stricter rate limits due to computational cost:
TierGenerations per MonthConcurrent Requests
Free Starter1001
Cloud Starter1,0003
Cloud PremiumUnlimited10
Exceeding rate limits will result in 429 Too Many Requests responses. Monitor your usage via Cloud Admin console.

Get Generation Status

Check generation progress and results

List Generations

View all your generation requests

Toggle Public

Make generations public or private

Delete Generation

Remove generation requests

AI Generation Guide

Implement in Starter Kit

Quick Start

Complete generation tutorial

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data
instructions
string
required
files
file[]
required

Response

Successful Response

id
string<uuid>
required
message
string
default:Generation request submitted successfully