✨ Imaginator API

Генерация изображений и видео с помощью AI

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

🚀 Быстрый старт

Примеры интеграции на разных языках программирования.

Python

import requests
import time
import base64

API_KEY = "ваш_api_ключ"
BASE_URL = "https://imaginator.mat3u.com/api/v1"

def generate_image(prompt, model="imagen3.5"):
    """Генерация изображения по тексту"""
    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"]
    
    # Ожидаем завершения
    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)

# Использование
url = generate_image("Космический корабль в стиле ретрофутуризма")
print(f"Результат: {url}")

JavaScript / Node.js

const API_KEY = 'ваш_api_ключ';
const BASE_URL = 'https://imaginator.mat3u.com/api/v1';

async function generateImage(prompt, model = 'imagen3.5') {
    // Создаём задачу
    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;
    
    // Ожидаем завершения
    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));
    }
}

// Использование
generateImage('Космический корабль в стиле ретрофутуризма')
    .then(url => console.log('Результат:', url));

cURL (Bash)

# Создание задачи
TASK_ID=$(curl -s -X POST https://imaginator.mat3u.com/api/v1/generate_image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{"prompt": "Футуристический город", "model": "nano_banana_pro"}' \
  | jq -r '.data.task_id')

echo "Task ID: $TASK_ID"

# Проверка статуса
curl -s https://imaginator.mat3u.com/api/v1/task/$TASK_ID \
  -H "X-API-Key: ваш_api_ключ" | jq

🔐 Авторизация

Все запросы к API требуют авторизации с помощью API ключа.

Передача API ключа

Передайте ключ в заголовке X-API-Key:

curl -H "X-API-Key: ваш_api_ключ" \
     https://imaginator.mat3u.com/api/v1/health

Или через Authorization: Bearer:

curl -H "Authorization: Bearer ваш_api_ключ" \
     https://imaginator.mat3u.com/api/v1/health

🖼️ Генерация изображений

POST /generate_image

Создаёт задачу на генерацию изображения. Задача выполняется асинхронно.

Параметры запроса

Параметр Тип Описание
prompt* string Текстовое описание изображения
modelопц. string imagen3.5, nano_banana, nano_banana_pro (×2 кредита). По умолчанию: imagen3.5
aspect_ratioопц. string landscape (16:9), portrait (9:16), square (1:1). По умолчанию: landscape
seedопц. integer Seed для воспроизводимости результата

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Футуристический город на закате, киберпанк стиль",
    "model": "nano_banana_pro",
    "aspect_ratio": "landscape"
  }'

Успешный ответ 201 Created

{
  "success": true,
  "data": {
    "task_id": "42",
    "status": "pending",
    "type": "image",
    "model": "imagen3.5",
    "aspect_ratio": "landscape",
    "estimated_time": "10-30 seconds",
    "remaining_quota": 249
  }
}

🎯 Генерация с референсами (Flow)

POST /generate_image_with_references

Генерация изображения на основе референсных изображений. Используется движок Flow (Nano Banana / Nano Banana Pro). Референсы влияют на стиль, персонажей и объекты в результате.

Параметры запроса

Параметр Тип Описание
prompt* string Текстовое описание изображения
image_base64_list* array Массив Base64 референсных изображений (1-5 штук)
modelопц. string nano_banana или nano_banana_pro (×2 кредита). По умолчанию: nano_banana_pro
aspect_ratioопц. string landscape (16:9), portrait (9:16), square (1:1). По умолчанию: landscape
seedопц. integer Seed для воспроизводимости результата

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_image_with_references \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Персонаж едет на машине по городу",
    "image_base64_list": [
      "base64_персонажа...",
      "base64_машины...",
      "base64_города..."
    ],
    "model": "nano_banana_pro",
    "aspect_ratio": "landscape"
  }'

Успешный ответ 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
  }
}

🎨 Генерация по рецепту (Whisk)

POST /generate_recipe

Генерация изображения по рецепту — комбинация объекта (subject), сцены (scene) и стиля (style) из загруженных изображений. Использует движок Whisk.

Параметры запроса

Параметр Тип Описание
promptопц. string Дополнительное текстовое описание
subject_image_base64* string Base64 изображение объекта (что генерировать)
scene_image_base64опц. string Base64 изображение сцены/фона
style_image_base64опц. string Base64 изображение стиля
aspect_ratioопц. string landscape, portrait, square. По умолчанию: landscape

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_recipe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Мой персонаж в космосе",
    "subject_image_base64": "base64_картинки_персонажа...",
    "scene_image_base64": "base64_картинки_космоса...",
    "aspect_ratio": "landscape"
  }'

Успешный ответ 201 Created

{
  "success": true,
  "data": {
    "task_id": "44",
    "status": "pending",
    "type": "image",
    "model": "whisk_recipe",
    "estimated_time": "15-45 seconds"
  }
}

🎬 Генерация видео

POST /generate_video

Создаёт задачу на генерацию видео с помощью Veo 3.1 Fast. Видео генерируется асинхронно за 30-60 секунд.

Параметры запроса

Параметр Тип Описание
prompt* string Текстовое описание видео
aspect_ratioопц. string landscape (16:9) или portrait (9:16). По умолчанию: landscape
seedопц. integer Seed для воспроизводимости результата
image_urlопц. string URL изображения для режима image-to-video

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_video \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Дрон пролетает над горами на рассвете",
    "aspect_ratio": "landscape"
  }'

Успешный ответ 201 Created

{
  "success": true,
  "data": {
    "task_id": "43",
    "status": "pending",
    "type": "video",
    "model": "veo3.1_fast",
    "aspect_ratio": "landscape",
    "estimated_time": "30-60 seconds",
    "remaining_quota": 1
  }
}

📹 Image-to-Video

Методы для генерации видео из изображений: анимация картинки, переходы между кадрами, видео с референсом.

POST /generate_video_from_image

Генерация видео из одного изображения (Image-to-Video / Whisk). Анимирует картинку по текстовому описанию.

⚠️ Только landscape — портретный режим не поддерживается.

Параметры запроса

Параметр Тип Описание
prompt* string Описание движения/действия в видео
image_base64* string Base64 изображение для анимации
loop_videoопц. boolean Зациклить видео. По умолчанию: false

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_video_from_image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Машина начинает движение и уезжает вдаль",
    "image_base64": "base64_картинки..."
  }'
POST /generate_video_transition

Генерация видео-перехода между двумя изображениями. Создаёт плавную анимацию от начального кадра к конечному.

⚠️ Только landscape — портретный режим не поддерживается.

Параметры запроса

Параметр Тип Описание
prompt* string Описание перехода
start_image_base64* string Base64 начального изображения
end_image_base64* string Base64 конечного изображения
aspect_ratioопц. string Только landscape
seedопц. integer Seed для воспроизводимости

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_video_transition \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Плавный морфинг между персонажами",
    "start_image_base64": "base64_начальной_картинки...",
    "end_image_base64": "base64_конечной_картинки..."
  }'
POST /generate_video_reference

Генерация видео с референсным изображением (Flow). Референс определяет стиль/персонажа, видео генерируется по промпту.

Параметры запроса

Параметр Тип Описание
prompt* string Описание действия в видео
reference_image_base64* string Base64 референсного изображения (персонаж, объект или стиль)
aspect_ratioопц. string landscape или portrait. По умолчанию: landscape
seedопц. integer Seed для воспроизводимости

Пример запроса

curl -X POST https://imaginator.mat3u.com/api/v1/generate_video_reference \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "prompt": "Персонаж танцует хип-хоп",
    "reference_image_base64": "base64_картинки_персонажа...",
    "aspect_ratio": "landscape"
  }'

📋 Управление задачами

GET /task/{task_id}

Получить статус и результат конкретной задачи.

Пример запроса

curl https://imaginator.mat3u.com/api/v1/task/42 \
  -H "X-API-Key: ваш_api_ключ"

Ответ (задача выполнена) 200 OK

{
  "success": true,
  "data": {
    "task_id": "42",
    "status": "completed",
    "type": "image",
    "provider": "google_imagen",
    "result_url": "https://lh3.googleusercontent.com/...",
    "created_at": "2026-01-18T20:04:47",
    "completed_at": "2026-01-18T20:04:55"
  }
}

Статусы задач

Статус Описание
pending Задача в очереди на выполнение
processing Задача выполняется
completed Задача успешно выполнена, результат доступен в result_url
failed Ошибка выполнения, описание в поле error
GET /tasks

Получить список всех ваших задач с пагинацией.

Query параметры

Параметр Тип Описание
page integer Номер страницы (по умолчанию: 1)
per_page integer Задач на странице (по умолчанию: 20, макс: 100)
status string Фильтр по статусу: pending, processing, completed, failed
type string Фильтр по типу: image или video

Пример запроса

curl "https://imaginator.mat3u.com/api/v1/tasks?page=1&status=completed&type=image" \
  -H "X-API-Key: ваш_api_ключ"

📊 Проверка квоты

GET /quota

Получить информацию о лимитах и текущем использовании.

Пример ответа 200 OK

{
  "success": true,
  "data": {
    "tier": "video_pro",
    "expires_at": "2026-02-18T20:00:00+03:00",
    "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,
      "concurrent_limit": 3,
      "active_tasks": 0
    }
  }
}

🤖 Доступные модели и методы

📋 Сводная таблица методов генерации

Endpoint Тип Движок Portrait Описание
/generate_image 🖼️ Image Whisk/Flow Текст → Изображение
/generate_image_with_references 🖼️ Image Flow Референсы + Текст → Изображение
/generate_recipe 🖼️ Image Whisk Subject + Scene + Style → Изображение
/generate_video 🎬 Video Flow (Veo) Текст → Видео (T2V)
/generate_video_from_image 📹 Video Whisk Изображение → Видео (I2V)
/generate_video_transition 📹 Video Flow 2 изображения → Переход
/generate_video_reference 📹 Video Flow Референс + Текст → Видео

🖼️ Модели для изображений

Модель Движок Кредиты Описание
imagen3.5 Whisk 1 Google Imagen 3.5 — быстрый и надёжный (по умолчанию)
nano_banana Flow 1 Nano Banana — продвинутая генерация
nano_banana_pro Flow ×2 Nano Banana Pro — лучшее качество

💡 Система кредитов

Модель nano_banana_pro расходует ×2 кредита за генерацию из-за повышенного качества. Например, при лимите 100 изображений в час:

  • 100 картинок imagen3.5 = 100 кредитов
  • 50 картинок nano_banana_pro = 100 кредитов
  • 40 imagen3.5 + 30 nano_banana_pro = 100 кредитов

Соотношения сторон (aspect_ratio)

Значение Соотношение Описание
landscape 16:9 Горизонтальное изображение
portrait 9:16 Вертикальное изображение
square 1:1 Квадратное изображение

🎬 Видео — Veo 3.1 Fast

Видео генерируются с помощью Google Veo 3.1 Fast через движок Flow — продвинутый режим для создания качественных видео за 30-60 секунд.

Соотношения сторон (aspect_ratio)

Значение Соотношение Описание
landscape 16:9 Горизонтальное видео (YouTube, презентации)
portrait 9:16 Вертикальное видео (TikTok, Reels, Shorts)

📎 Работа с Base64 изображениями

Для методов генерации из изображений (Recipe, I2V, Transition, Reference) необходимо передавать изображения в формате Base64.

⚠️ Важные ограничения

  • Поддерживаемые форматы: JPEG, PNG, WebP, GIF
  • Максимальный размер файла: 10 МБ
  • Рекомендуемое разрешение: 1024x1024 — 2048x2048
  • Передавайте чистый Base64 без префикса data:image/...

Python — конвертация в Base64

import base64

def image_to_base64(file_path):
    """Конвертирует файл изображения в Base64 строку"""
    with open(file_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

# Из URL
import requests

def url_to_base64(url):
    """Скачивает изображение по URL и конвертирует в Base64"""
    response = requests.get(url)
    return base64.b64encode(response.content).decode("utf-8")

# Пример использования
subject_b64 = image_to_base64("персонаж.jpg")
scene_b64 = url_to_base64("https://example.com/background.png")

response = requests.post(
    "https://imaginator.mat3u.com/api/v1/generate_recipe",
    headers={"X-API-Key": API_KEY},
    json={
        "prompt": "Мой персонаж на этом фоне",
        "subject_image_base64": subject_b64,
        "scene_image_base64": scene_b64
    }
)

JavaScript — конвертация в Base64

// В браузере из input[type="file"]
async function fileToBase64(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => {
            // Убираем префикс "data:image/...;base64,"
            const base64 = reader.result.split(',')[1];
            resolve(base64);
        };
        reader.onerror = reject;
    });
}

// В Node.js из файла
const fs = require('fs');

function fileToBase64(filePath) {
    const buffer = fs.readFileSync(filePath);
    return buffer.toString('base64');
}

// Из URL (Node.js)
async function urlToBase64(url) {
    const response = await fetch(url);
    const buffer = Buffer.from(await response.arrayBuffer());
    return buffer.toString('base64');
}

Полный пример: Image-to-Video

import requests
import base64
import time

API_KEY = "ваш_api_ключ"
BASE_URL = "https://imaginator.mat3u.com/api/v1"

# 1. Подготовка изображения
with open("машина.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# 2. Создание задачи на генерацию видео
response = requests.post(
    f"{BASE_URL}/generate_video_from_image",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "prompt": "Машина начинает движение и уезжает вдаль",
        "image_base64": image_b64
    }
)
task_id = response.json()["data"]["task_id"]
print(f"Задача создана: {task_id}")

# 3. Ожидание результата (видео ~30-60 сек)
while True:
    status = requests.get(
        f"{BASE_URL}/task/{task_id}",
        headers={"X-API-Key": API_KEY}
    ).json()
    
    state = status["data"]["status"]
    print(f"Статус: {state}")
    
    if state == "completed":
        print(f"✅ Видео готово: {status['data']['result_url']}")
        break
    elif state == "failed":
        print(f"❌ Ошибка: {status['data'].get('error_message')}")
        break
    
    time.sleep(5)

⚠️ Коды ошибок

HTTP код Код ошибки Описание
401 AUTH_REQUIRED API ключ не передан
401 INVALID_API_KEY Неверный API ключ
403 API_KEY_DISABLED API ключ отключен
403 API_KEY_EXPIRED Срок действия API ключа истёк
429 NO_ACTIVE_LICENSE Нет активной лицензии
429 HOURLY_LIMIT_EXCEEDED Превышен часовой лимит
429 CONCURRENT_LIMIT_EXCEEDED Превышен лимит одновременных задач
400 INVALID_REQUEST Некорректные параметры запроса
404 TASK_NOT_FOUND Задача не найдена
500 SERVER_ERROR Внутренняя ошибка сервера

Формат ответа с ошибкой

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