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.
Bearer JWT access token obtained from login
Developer key associated with the project
Project UUID for project-scoped access
Project API key for authentication
Must be multipart/form-data for file uploads
Request Body (Multipart Form Data)
Array of 1-5 example images to guide generation. Supported formats: JPEG, PNG, WebP. Maximum 10MB per image.
JSON-encoded string containing generation instructions. Must be between 1-1000 characters when serialized. Example: {"prompt": "Generate a futuristic cityscape with neon lights"}
Response
Unique UUID identifier for the generation request
Initial status: always pending for new requests
Confirmation message: “Generation request submitted successfully”
Example Request
curl -X POST https://api.vibecoding.ad/api/v1/generation/generate-v2 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "X-User-Role: end_user" \
-H "X-Developer-Key: ak_abc123XYZ-_789def456ghi012jkl345" \
-H "X-Project-ID: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-API-Key: pk_xyz789ABC-_123def456ghi012jkl345" \
-F "example_images=@/path/to/image1.jpg" \
-F "example_images=@/path/to/image2.jpg" \
-F "example_images=@/path/to/image3.jpg" \
-F 'instructions={"prompt": "Generate a futuristic cityscape with neon lights and flying cars", "style": "cyberpunk"}'
Example Response
{
"id" : "990e8400-e29b-41d4-a716-446655440004" ,
"status" : "pending" ,
"message" : "Generation request submitted successfully"
}
Generation Status Lifecycle
After submission, the generation progresses through multiple states:
pending - Request queued for processing
processing - AI model actively generating image
completed - Generation successful, image available
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
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
The instructions field must be a JSON-encoded string with the following constraints:
Structure:
{
"prompt" : "Your generation prompt here" ,
"style" : "Optional style modifier" ,
"additional_params" : "Any additional instructions"
}
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:
{ "prompt" : "Generate a sunset over mountains" }
{
"prompt" : "Create a modern minimalist interior design" ,
"style" : "scandinavian" ,
"mood" : "calm and serene"
}
{
"prompt" : "Generate a fantasy landscape with magical elements" ,
"style" : "concept art" ,
"details" : "include floating islands and glowing crystals"
}
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:
async function generatePortfolioImage (
examples : File [],
prompt : string ,
authHeaders : HeadersInit
) : Promise < string > {
const formData = new FormData ();
// Add example images
examples . forEach ( file => {
formData . append ( 'example_images' , file );
});
// Add instructions
formData . append ( 'instructions' , JSON . stringify ({
prompt ,
style: 'professional photography'
}));
const response = await fetch (
'https://api.vibecoding.ad/api/v1/generation/generate-v2' ,
{
method: 'POST' ,
headers: authHeaders , // Include all required auth headers
body: formData
}
);
const data = await response . json ();
return data . id ; // Return generation ID for status polling
}
E-Commerce Product Variations
Create product variations for online stores:
async function generateProductVariations (
productImages : File [],
variations : string []
) : Promise < string []> {
const generationIds : string [] = [];
for ( const variation of variations ) {
const formData = new FormData ();
productImages . forEach ( img => formData . append ( 'example_images' , img ));
formData . append ( 'instructions' , JSON . stringify ({
prompt: `Generate ${ variation } variation of the product` ,
style: 'product photography' ,
background: 'white'
}));
const response = await fetch ( apiUrl , {
method: 'POST' ,
headers: authHeaders ,
body: formData
});
const data = await response . json ();
generationIds . push ( data . id );
}
return generationIds ;
}
Content Creation Platform
Build a content creation tool with AI generation:
interface GenerationRequest {
images : File [];
prompt : string ;
style ?: string ;
mood ?: string ;
}
async function createContent ( request : GenerationRequest ) {
const formData = new FormData ();
request . images . forEach ( img => {
formData . append ( 'example_images' , img );
});
const instructions = {
prompt: request . prompt ,
... ( request . style && { style: request . style }),
... ( request . mood && { mood: request . mood })
};
formData . append ( 'instructions' , JSON . stringify ( instructions ));
// Submit generation
const response = await fetch ( apiUrl , {
method: 'POST' ,
headers: authHeaders ,
body: formData
});
const { id } = await response . json ();
// Poll for completion
return await pollGenerationStatus ( id );
}
Error Responses
Missing Example Images (422)
{
"detail" : [
{
"loc" : [ "body" , "example_images" ],
"msg" : "field required" ,
"type" : "value_error.missing"
}
]
}
Too Many Images (422)
{
"detail" : "Maximum 5 example images allowed"
}
File Too Large (413)
{
"detail" : "File size exceeds maximum allowed size of 10MB"
}
{
"detail" : "Invalid file format. Supported formats: JPEG, PNG, WebP"
}
Invalid Instructions (422)
{
"detail" : [
{
"loc" : [ "body" , "instructions" ],
"msg" : "Invalid JSON format" ,
"type" : "value_error.json"
}
]
}
Instructions Too Long (422)
{
"detail" : "Instructions must be between 1 and 1000 characters"
}
Unauthorized (401)
{
"detail" : "Could not validate credentials"
}
Insufficient Permissions (403)
{
"detail" : "Insufficient permissions for this operation"
}
Rate Limit Exceeded (429)
{
"detail" : "AI generation rate limit exceeded. Try again later." ,
"retry_after" : 3600
}
Rate Limits
AI generation endpoints have stricter rate limits due to computational cost:
Tier Generations per Month Concurrent Requests Free Starter 100 1 Cloud Starter 1,000 3 Cloud Premium Unlimited 10
Exceeding rate limits will result in 429 Too Many Requests responses. Monitor your usage via Cloud Admin console .
Related Pages
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
Bearer authentication header of the form Bearer <token> , where <token> is your auth token.
message
string
default: Generation request submitted successfully