✨ Imaginator API

AI-powered image and video generation

https://imaginator.mat3u.com/api/v1

🚀 Quick Start

Integration examples in different programming languages.

Python

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://imaginator.mat3u.com/api/v1"

def generate_image(prompt, model="imagen3.5"):
    """Generate image from text prompt"""
    response = requests.post(
        f"{BASE_URL}/generate_image",
        headers={"X-API-Key": API_KEY},
        json={"prompt": prompt, "model": model}
    )
    task_id = response.json()["data"]["task_id"]
    
    # Wait for completion
    while True:
        status = requests.get(
            f"{BASE_URL}/task/{task_id}",
            headers={"X-API-Key": API_KEY}
        ).json()
        
        if status["data"]["status"] == "completed":
            return status["data"]["result_url"]
        elif status["data"]["status"] == "failed":
            raise Exception(status["data"].get("error_message"))
        
        time.sleep(2)

# Usage
url = generate_image("A spaceship in retro-futuristic style")
print(f"Result: {url}")

JavaScript / Node.js

const API_KEY = 'your_api_key';
const BASE_URL = 'https://imaginator.mat3u.com/api/v1';

async function generateImage(prompt, model = 'imagen3.5') {
    // Create task
    const response = await fetch(`${BASE_URL}/generate_image`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        },
        body: JSON.stringify({ prompt, model })
    });
    
    const { data } = await response.json();
    const taskId = data.task_id;
    
    // Wait for completion
    while (true) {
        const status = await fetch(`${BASE_URL}/task/${taskId}`, {
            headers: { 'X-API-Key': API_KEY }
        }).then(r => r.json());
        
        if (status.data.status === 'completed') {
            return status.data.result_url;
        } else if (status.data.status === 'failed') {
            throw new Error(status.data.error_message);
        }
        
        await new Promise(r => setTimeout(r, 2000));
    }
}

// Usage
generateImage('A spaceship in retro-futuristic style')
    .then(url => console.log('Result:', url));

cURL (Bash)

# Create task
TASK_ID=$(curl -s -X POST https://imaginator.mat3u.com/api/v1/generate_image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"prompt": "Futuristic city", "model": "nano_banana_pro"}' \
  | jq -r '.data.task_id')

echo "Task ID: $TASK_ID"

# Check status
curl -s https://imaginator.mat3u.com/api/v1/task/$TASK_ID \
  -H "X-API-Key: your_api_key" | jq

🔐 Authentication

All API requests require authentication via API key.

Passing API Key

Pass the key in X-API-Key header:

curl -H "X-API-Key: your_api_key" \
     https://imaginator.mat3u.com/api/v1/health

Or via Authorization: Bearer:

curl -H "Authorization: Bearer your_api_key" \
     https://imaginator.mat3u.com/api/v1/health

🖼️ Image Generation

POST /generate_image

Creates an image generation task. Task is processed asynchronously.

Request Parameters

ParameterTypeDescription
prompt* string Text description of the image
modelopt. string imagen3.5, nano_banana, nano_banana_pro (×2 credits). Default: imagen3.5
aspect_ratioopt. string landscape (16:9), portrait (9:16), square (1:1). Default: landscape
seedopt. integer Seed for reproducible results

Example Request

curl -X POST https://imaginator.mat3u.com/api/v1/generate_image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "prompt": "Futuristic city at sunset, cyberpunk style",
    "model": "nano_banana_pro",
    "aspect_ratio": "landscape"
  }'

Success Response 201 Created

{
  "success": true,
  "data": {
    "task_id": "42",
    "status": "pending",
    "type": "image",
    "model": "nano_banana_pro",
    "estimated_time": "10-30 seconds",
    "remaining_quota": 249
  }
}

🎯 Generation with References (Flow)

POST /generate_image_with_references

Generate image based on reference images. Uses Flow engine (Nano Banana / Nano Banana Pro). References influence style, characters and objects in the result.

Request Parameters

ParameterTypeDescription
prompt* string Text description of the image
image_base64_list* array Array of Base64 reference images (1-5 images)
modelopt. string nano_banana or nano_banana_pro (×2 credits). Default: nano_banana_pro
aspect_ratioopt. string landscape (16:9), portrait (9:16), square (1:1). Default: landscape
seedopt. integer Seed for reproducible results

Example Request

curl -X POST https://imaginator.mat3u.com/api/v1/generate_image_with_references \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "prompt": "Character driving a car through the city",
    "image_base64_list": [
      "base64_character...",
      "base64_car...",
      "base64_city..."
    ],
    "model": "nano_banana_pro",
    "aspect_ratio": "landscape"
  }'

Success Response 201 Created

{
  "success": true,
  "data": {
    "task_id": "45",
    "status": "pending",
    "type": "image",
    "model": "nano_banana_pro",
    "reference_count": 3,
    "estimated_time": "15-45 seconds",
    "remaining_quota": 248
  }
}

🎨 Recipe Generation (Whisk)

POST /generate_recipe

Generate image from recipe — combination of subject, scene and style from uploaded images. Uses Whisk engine.

Request Parameters

ParameterTypeDescription
promptopt. string Additional text description
subject_image_base64* string Base64 subject image (what to generate)
scene_image_base64opt. string Base64 scene/background image
style_image_base64opt. string Base64 style image
aspect_ratioopt. string landscape, portrait, square. Default: landscape

🎬 Video Generation

POST /generate_video

Creates a video generation task using Veo 3.1 Fast. Video is generated asynchronously in 30-60 seconds.

Request Parameters

ParameterTypeDescription
prompt* string Text description of the video
aspect_ratioopt. string landscape (16:9) or portrait (9:16). Default: landscape
seedopt. integer Seed for reproducible results

Example Request

curl -X POST https://imaginator.mat3u.com/api/v1/generate_video \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "prompt": "Drone flying over mountains at sunrise",
    "aspect_ratio": "landscape"
  }'

📹 Image-to-Video

Methods for generating video from images: image animation, transitions, reference-based video.

POST /generate_video_from_image

Generate video from single image (Image-to-Video / Whisk). Animates the image based on text description.

⚠️ Landscape only — portrait mode is not supported.

Request Parameters

ParameterTypeDescription
prompt* string Description of movement/action in video
image_base64* string Base64 image to animate
loop_videoopt. boolean Loop the video. Default: false
POST /generate_video_transition

Generate video transition between two images. Creates smooth animation from start frame to end frame.

⚠️ Landscape only — portrait mode is not supported.

Request Parameters

ParameterTypeDescription
prompt* string Transition description
start_image_base64* string Base64 start image
end_image_base64* string Base64 end image
POST /generate_video_reference

Generate video with reference image (Flow). Reference defines style/character, video is generated from prompt.

Request Parameters

ParameterTypeDescription
prompt* string Description of action in video
reference_image_base64* string Base64 reference image (character, object or style)
aspect_ratioopt. string landscape or portrait. Default: landscape

📋 Task Management

GET /task/{task_id}

Get status and result of a specific task.

Task Statuses

StatusDescription
pendingTask is queued for processing
processingTask is being processed
completedTask completed successfully, result available in result_url
failedProcessing error, description in error field
GET /tasks

Get list of all your tasks with pagination.

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerTasks per page (default: 20, max: 100)
statusstringFilter by status: pending, processing, completed, failed
typestringFilter by type: image or video

📊 Quota Check

GET /quota

Get information about limits and current usage.

Response Example 200 OK

{
  "success": true,
  "data": {
    "tier": "video_pro",
    "images": {
      "hourly_limit": 4000,
      "used_this_hour": 15,
      "remaining": 3985,
      "concurrent_limit": 5,
      "active_tasks": 1
    },
    "videos": {
      "hourly_limit": 150,
      "used_this_hour": 3,
      "remaining": 147
    }
  }
}

🤖 Available Models

🖼️ Image Models

ModelEngineCreditsDescription
imagen3.5 Whisk 1 Google Imagen 3.5 — fast and reliable (default)
nano_banana Flow 1 Nano Banana — advanced generation
nano_banana_pro Flow ×2 Nano Banana Pro — best quality

💡 Credits System

Model nano_banana_pro uses ×2 credits per generation due to enhanced quality. For example, with 100 images/hour limit:

  • 100 images with imagen3.5 = 100 credits
  • 50 images with nano_banana_pro = 100 credits
  • 40 imagen3.5 + 30 nano_banana_pro = 100 credits

📋 Generation Methods Summary

EndpointTypeEnginePortraitDescription
/generate_image🖼️ ImageWhisk/FlowText → Image
/generate_image_with_references🖼️ ImageFlowReferences + Text → Image
/generate_recipe🖼️ ImageWhiskSubject + Scene + Style → Image
/generate_video🎬 VideoFlow (Veo)Text → Video (T2V)
/generate_video_from_image📹 VideoWhiskImage → Video (I2V)
/generate_video_transition📹 VideoFlow2 Images → Transition
/generate_video_reference📹 VideoFlowReference + Text → Video

⚠️ Error Codes

HTTP CodeError CodeDescription
401AUTH_REQUIREDAPI key not provided
401INVALID_API_KEYInvalid API key
403API_KEY_DISABLEDAPI key is disabled
403API_KEY_EXPIREDAPI key expired
429NO_ACTIVE_LICENSENo active license
429HOURLY_LIMIT_EXCEEDEDHourly limit exceeded
429CONCURRENT_LIMIT_EXCEEDEDConcurrent tasks limit exceeded
400INVALID_REQUESTInvalid request parameters
404TASK_NOT_FOUNDTask not found
500SERVER_ERRORInternal server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "HOURLY_LIMIT_EXCEEDED",
    "message": "Hourly image limit exceeded (250/hour)"
  }
}