Create Generation - Dev Kit for AI

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

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

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

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:

{
  "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"
}

Invalid File Format (422)

{
  "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.

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

string<uuid>

required

message

string

default:Generation request submitted successfully

API documentation

Health Check

Authentication

Project Management

AI Generation

Health Check API

Authentication

Project Management

AI Generation API

Default

​Authentication

​Headers

​Request Body (Multipart Form Data)

​Response

​Example Request

​Example Response

​Generation Status Lifecycle

​Image Requirements

​File Formats

​File Size

​Image Count

​Image Quality

​Instructions Format

​Processing Time

​Use Cases

​Portfolio Website

​E-Commerce Product Variations

​Content Creation Platform

​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

​Related Pages

Get Generation Status

List Generations

Toggle Public

Delete Generation

AI Generation Guide

Quick Start

Authorizations

Body

Response

Authentication

Headers

Request Body (Multipart Form Data)

Response

Example Request

Example Response

Generation Status Lifecycle

Image Requirements

File Formats

File Size

Image Count

Image Quality

Instructions Format

Processing Time

Use Cases

Portfolio Website

E-Commerce Product Variations

Content Creation Platform

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

Related Pages