Caricatu.ro
Caricatu.ro
Home API Documentation
Login Sign Up
Select Language
🇺🇸 EN

API Documentation

Integrate AI-powered caricature generation into your applications with our powerful RESTful API.

Sign Up for API Access

Getting Started

API Caricatu.ro allows you to programmatically generate caricatures using AI. Our API is RESTful and returns JSON responses with asynchronous processing.

Base URL

https://caricatu.ro/api/v1

Quick Start

  1. Create an account and get an API key on the settings page
  2. Send a POST request to generate a caricature
  3. Upload an image and specify the desired style
  4. Get order_id and check status until completion
  5. Download ready caricatures from the obtained URLs

Real AI Generation

API uses advanced machine learning algorithms to create unique caricatures. Processing takes 1-2 minutes to ensure high-quality results.

Authentication

All API requests require authentication using your API key. Include the API key in the request headers.

Headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
⚠️

Keep API Key Secure

Never expose your API key in client code. Always make API calls from your server.

💡

Example API Key

Your API key looks something like this:

your_api_key_here_64_characters_long_example_1234567890abcdef

API Endpoints

POST /generate

Create a caricature from uploaded image. Returns order_id for tracking status.

Request Body

{
  "image": "base64_encoded_image_data",
  "style": "simple_caricature",
  "custom_prompt": "anime style with large eyes",
  "options": {
    "quality": "high",
    "format": "jpg"
  }
}

Parameters

Parameter Type Required Description
image string Yes Base64 encoded image data (JPG, PNG, WebP, HEIC up to 50MB)
style string No Predefined style: "simple_caricature" or "custom_transformation"
custom_prompt string No Description of custom style (max. 500 characters)
options.quality string No Output quality: "standard" or "high" (default: "high")
options.format string No Output format: "jpg" or "png" (default: "jpg")

Response (HTTP 202 Accepted)

{
  "success": true,
  "order_id": 47,
  "status": "pending",
  "credits_used": 1,
  "message": "Order created successfully. Use the orders endpoint to check status.",
  "estimated_time": "1-2 minutes",
  "created_at": "2025-06-14T15:00:43+00:00"
}
ℹ️

Asynchronous Processing

API returns HTTP 202 (Accepted) and immediately provides order_id. Use endpoint /orders/{order_id} to check status and get results.

GET /orders/{order_id}

Get status and results of a specific order. Use for tracking progress of generation.

Response (in progress)

{
  "success": true,
  "order": {
    "id": 47,
    "status": "in_progress",
    "credits_used": 1,
    "progress": 65,
    "created_at": "2025-06-14T15:00:43+00:00",
    "estimated_completion": "2025-06-14T15:02:00+00:00"
  }
}

Response (completed)

{
  "success": true,
  "order": {
    "id": 47,
    "status": "completed",
    "credits_used": 1,
    "results": {
      "original_url": "https://caricatu.ro/uploads/api_upload_47_1749900526.jpg",
      "caricature_url": "https://caricatu.ro/uploads/api_caricature_47_1749900526.jpg"
    },
    "created_at": "2025-06-14T15:00:43+00:00",
    "completed_at": "2025-06-14T15:01:52+00:00",
    "processing_time": 69
  }
}
💡

Order Statuses

  • pending - order created, waiting for processing
  • in_progress - AI generating caricature
  • completed - caricature ready, URLs available
  • failed - processing error
GET /account

Get information about your account and credit balance.

Response

{
  "success": true,
  "account": {
    "user_id": 5,
    "credits_remaining": 87,
    "api_calls_today": 3,
    "api_calls_total": 15,
    "plan": "free"
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 97,
    "reset": 1749900600
  }
}

Error Handling

API uses standard HTTP response codes to indicate success or failure. All errors include JSON body with details.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits for this operation",
    "details": {
      "credits_required": 1,
      "credits_available": 0
    }
  }
}

HTTP Status Codes

Status Code Value
200 Success
202 Accepted - order created, processing asynchronously
400 Bad Request - incorrect parameters
401 Unauthorized - incorrect API key
402 Payment Required - insufficient credits
429 Too Many Requests - exceeded limit
500 Internal Server Error

Rate Limits

To ensure fair usage and optimal performance, API has limits based on your account type.

Free Plan

  • • 10 requests per hour
  • • 50 requests per day
  • • 1 simultaneous request

Paid Plans

  • • 100 requests per hour
  • • 1000 requests per day
  • • 5 simultaneous requests

Rate Limit Headers

Each API response includes rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1749900600

Code Examples

JavaScript (Node.js)

const fs = require('fs');
const fetch = require('node-fetch');

async function generateCaricature(imagePath, style = 'simple_caricature') {
  try {
    // Read and encode image
    const imageBuffer = fs.readFileSync(imagePath);
    const base64Image = imageBuffer.toString('base64');
    
    // Create order
    const response = await fetch('https://caricatu.ro/api/v1/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        image: base64Image,
        style: style,
        options: {
          quality: 'high',
          format: 'jpg'
        }
      })
    });
    
    const result = await response.json();
    
    if (!result.success) {
      throw new Error(result.error.message);
    }
    
    console.log(`Order created: ${result.order_id}`);
    console.log('Waiting for completion...');
    
    // Poll for completion
    const orderId = result.order_id;
    let completed = false;
    
    while (!completed) {
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
      
      const statusResponse = await fetch(`https://caricatu.ro/api/v1/orders/${orderId}`, {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      });
      
      const statusResult = await statusResponse.json();
      
      if (statusResult.success) {
        const order = statusResult.order;
        console.log(`Status: ${order.status}`);
        
        if (order.status === 'completed') {
          console.log('Caricature generated successfully!');
          console.log('Original:', order.results.original_url);
          console.log('Caricature:', order.results.caricature_url);
          completed = true;
          return order;
        } else if (order.status === 'failed') {
          throw new Error('Generation failed');
        }
      }
    }
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

// Usage
generateCaricature('./path/to/your/photo.jpg', 'simple_caricature')
  .then(result => console.log('Done!', result))
  .catch(error => console.error('Failed:', error));

Python

import requests
import base64
import time

def generate_caricature(image_path, style='simple_caricature', api_key='YOUR_API_KEY'):
    try:
        # Read and encode image
        with open(image_path, 'rb') as image_file:
            base64_image = base64.b64encode(image_file.read()).decode('utf-8')
        
        # Create order
        url = 'https://caricatu.ro/api/v1/generate'
        headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
        
        data = {
            'image': base64_image,
            'style': style,
            'options': {
                'quality': 'high',
                'format': 'jpg'
            }
        }
        
        response = requests.post(url, headers=headers, json=data)
        result = response.json()
        
        if not result['success']:
            raise Exception(result['error']['message'])
        
        order_id = result['order_id']
        print(f"Order created: {order_id}")
        print("Waiting for completion...")
        
        # Poll for completion
        while True:
            time.sleep(5)  # Wait 5 seconds
            
            status_url = f'https://caricatu.ro/api/v1/orders/{order_id}'
            status_response = requests.get(status_url, headers=headers)
            status_result = status_response.json()
            
            if status_result['success']:
                order = status_result['order']
                print(f"Status: {order['status']}")
                
                if order['status'] == 'completed':
                    print("Caricature generated successfully!")
                    print(f"Original: {order['results']['original_url']}")
                    print(f"Caricature: {order['results']['caricature_url']}")
                    return order
                elif order['status'] == 'failed':
                    raise Exception("Generation failed")
            else:
                raise Exception("Failed to check status")
                
    except Exception as e:
        print(f"Error: {e}")
        raise

# Usage
if __name__ == "__main__":
    try:
        # Replace 'photo.jpg' with path to your actual image file
        result = generate_caricature('path/to/your/photo.jpg', 'simple_caricature')
        print("Done!", result)
    except Exception as e:
        print(f"Failed: {e}")

PHP

Error: Image file not found: path/to/your/photo.jpg
Failed: Image file not found: path/to/your/photo.jpg

Official SDKs

We're working on official SDKs for popular programming languages to make integration even easier.

📦

JavaScript/TypeScript

Coming Soon

In Development
🐍

Python

Coming Soon

In Development
🐘

PHP

Coming Soon

In Development

Need Help?

Have questions about our API? Our support team is ready to help you successfully integrate our service.

🚀

Ready to Start?

Create an account, get an API key, and start generating caricatures today!