🚀 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
Creates an image generation task. Task is processed asynchronously.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
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)
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
| Parameter | Type | Description |
|---|---|---|
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)
Generate image from recipe — combination of subject, scene and style from uploaded images. Uses Whisk engine.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
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
Creates a video generation task using Veo 3.1 Fast. Video is generated asynchronously in 30-60 seconds.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
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.
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
| Parameter | Type | Description |
|---|---|---|
prompt* |
string | Description of movement/action in video |
image_base64* |
string | Base64 image to animate |
loop_videoopt. |
boolean | Loop the video. Default: false |
Generate video transition between two images. Creates smooth animation from start frame to end frame.
⚠️ Landscape only — portrait mode is not supported.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
prompt* |
string | Transition description |
start_image_base64* |
string | Base64 start image |
end_image_base64* |
string | Base64 end image |
Generate video with reference image (Flow). Reference defines style/character, video is generated from prompt.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
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 status and result of a specific task.
Task Statuses
| Status | Description |
|---|---|
pending | Task is queued for processing |
processing | Task is being processed |
completed | Task completed successfully, result available in result_url |
failed | Processing error, description in error field |
Get list of all your tasks with pagination.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Tasks per page (default: 20, max: 100) |
status | string | Filter by status: pending, processing, completed, failed |
type | string | Filter by type: image or video |
📊 Quota Check
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
| Model | Engine | Credits | Description |
|---|---|---|---|
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+ 30nano_banana_pro= 100 credits
📋 Generation Methods Summary
| Endpoint | Type | Engine | Portrait | Description |
|---|---|---|---|---|
/generate_image | 🖼️ Image | Whisk/Flow | ✅ | Text → Image |
/generate_image_with_references | 🖼️ Image | Flow | ✅ | References + Text → Image |
/generate_recipe | 🖼️ Image | Whisk | ✅ | Subject + Scene + Style → Image |
/generate_video | 🎬 Video | Flow (Veo) | ✅ | Text → Video (T2V) |
/generate_video_from_image | 📹 Video | Whisk | ❌ | Image → Video (I2V) |
/generate_video_transition | 📹 Video | Flow | ❌ | 2 Images → Transition |
/generate_video_reference | 📹 Video | Flow | ✅ | Reference + Text → Video |
⚠️ Error Codes
| HTTP Code | Error Code | Description |
|---|---|---|
| 401 | AUTH_REQUIRED | API key not provided |
| 401 | INVALID_API_KEY | Invalid API key |
| 403 | API_KEY_DISABLED | API key is disabled |
| 403 | API_KEY_EXPIRED | API key expired |
| 429 | NO_ACTIVE_LICENSE | No active license |
| 429 | HOURLY_LIMIT_EXCEEDED | Hourly limit exceeded |
| 429 | CONCURRENT_LIMIT_EXCEEDED | Concurrent tasks limit exceeded |
| 400 | INVALID_REQUEST | Invalid request parameters |
| 404 | TASK_NOT_FOUND | Task not found |
| 500 | SERVER_ERROR | Internal server error |
Error Response Format
{
"success": false,
"error": {
"code": "HOURLY_LIMIT_EXCEEDED",
"message": "Hourly image limit exceeded (250/hour)"
}
}