🚀 Быстрый старт
Примеры интеграции на разных языках программирования.
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
🖼️ Генерация изображений
Создаёт задачу на генерацию изображения. Задача выполняется асинхронно.
Параметры запроса
| Параметр | Тип | Описание |
|---|---|---|
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)
Генерация изображения на основе референсных изображений. Используется движок 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)
Генерация изображения по рецепту — комбинация объекта (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"
}
}
🎬 Генерация видео
Создаёт задачу на генерацию видео с помощью 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
Методы для генерации видео из изображений: анимация картинки, переходы между кадрами, видео с референсом.
Генерация видео из одного изображения (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_картинки..."
}'
Генерация видео-перехода между двумя изображениями. Создаёт плавную анимацию от начального кадра к конечному.
⚠️ Только 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_конечной_картинки..."
}'
Генерация видео с референсным изображением (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"
}'
📋 Управление задачами
Получить статус и результат конкретной задачи.
Пример запроса
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 |
Получить список всех ваших задач с пагинацией.
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_ключ"
📊 Проверка квоты
Получить информацию о лимитах и текущем использовании.
Пример ответа 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+ 30nano_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)"
}
}