Ludo AI MCP Server
Создавайте игровые ресурсы с помощью AI через Model Context Protocol (MCP).
Возможности
| Категория | Возможности |
|---|---|
| Изображения | Спрайты, значки, снимки экрана, фоны, элементы интерфейса, текстуры, удаление фона, увеличение разрешения |
| 3D-модели | Изображения персонажей, готовые для создания 3D-модели (по текстовому запросу или на основе вашего изображения, преобразованного в 3D-рендер); преобразование 2D-изображений в модели GLB с PBR-текстурами (объекты или более детализированные модели героев, которые при необходимости можно оснастить скелетом в том же запросе); автоматическое создание скелета для моделей (скелет и веса вершин, названия суставов, готовые для игрового движка); создание скелетной анимации по текстовому описанию; перенос подобранных пресетов анимации на модели со скелетом |
| Спрайты с разных ракурсов | Создавайте стилизованные спрайты 3D-модели с ракурсов до 8 направлений, согласованных между собой: от пиксельной графики до живописи и 3D-рендеров. Используйте пресет анимации или собственный клип; перед рендерингом можно бесплатно посмотреть результат |
| Анимация | Анимированные спрайтовые листы на основе статичных спрайтов (4–64 кадра); анимация по ключевым кадрам с использованием до трёх фиксированных кадров; перенос движения из видео или пресетов; редактирование спрайтовых листов (повторный запрос, дорисовка за границами изображения, исправление зацикливания, повторный рендер с повышенной детализацией); создание звуковых эффектов для спрайтового листа |
| Видео | Создание коротких видео на основе изображений или референсов (5–15 секунд, с саундтреком); редактирование видео по текстовому запросу; увеличение разрешения в 2 раза |
| Аудио | Звуковые эффекты, фоновая музыка, голоса персонажей, TTS |
| Задания и история | Очередь асинхронных заданий: отправка, проверка статуса или длительное ожидание ответа, просмотр и отмена заданий (за задания в очереди возвращаются кредиты); постраничная история генераций в API и веб-приложении |
| Аккаунт | Баланс кредитов, тарифный план и настройки автоматического пополнения — их можно проверить перед дорогостоящей генерацией |
| Документация | Перед генерацией ищите рекомендации Ludo по использованию функций: режимы анимации, выбор модели, поля и известные ограничения |
| Обратная связь | Сообщайте команде Ludo об ограничениях, ошибках и недостающих возможностях |
Быстрый старт
1. Получите API-ключ
Доступ к API входит в тарифные планы Pro и Studio. Создайте ключ на странице app.ludo.ai/api-keys; он отображается только один раз.
Используете агента для написания кода (Claude Code, Codex, Cursor)? В этом случае лучше подойдёт Ludo CLI: агент загружает только нужные ему команды, а файлы передаются по путям.
2. Настройте MCP-клиент
Сервер работает по протоколу Streamable HTTP и доступен по адресу https://mcp.ludo.ai/mcp. Каждый клиент передаёт ключ в заголовке:
Authorization: ApiKey YOUR_API_KEY
Инструкции по настройке для одиннадцати клиентов, включая Windsurf, Cline, Zed и Kiro, доступны на странице ludo.ai/developers/mcp.
Claude Code
claude mcp add --transport http ludo https://mcp.ludo.ai/mcp --header "Authorization: ApiKey YOUR_API_KEY"
Добавьте -s user, чтобы использовать сервер во всех проектах.
Claude Desktop и claude.ai
Откройте Customize > Connectors, нажмите Add, затем выберите Add custom connector. Назовите подключение Ludo, укажите URL https://mcp.ludo.ai/mcp и добавьте Authorization: ApiKey YOUR_API_KEY в разделе Request headers. (claude_desktop_config.json предназначен только для запуска локальных серверов; удалённый сервер нужно добавить как подключение.)
Codex
Добавьте настройки в ~/.codex/config.toml:
[mcp_servers.ludo]
url = "https://mcp.ludo.ai/mcp"
[mcp_servers.ludo.http_headers]
Authorization = "ApiKey YOUR_API_KEY"
Cursor
Добавьте настройки в ~/.cursor/mcp.json (или в .cursor/mcp.json в проекте):
{
"mcpServers": {
"ludo": {
"url": "https://mcp.ludo.ai/mcp",
"headers": {
"Authorization": "ApiKey YOUR_API_KEY"
}
}
}
}
VS Code
Добавьте настройки в .vscode/mcp.json, затем используйте Copilot Chat в режиме Agent. VS Code запросит ключ один раз и сохранит его в защищённом хранилище:
{
"inputs": [
{ "type": "promptString", "id": "ludo-api-key", "description": "Ludo.ai API key", "password": true }
],
"servers": {
"ludo": {
"type": "http",
"url": "https://mcp.ludo.ai/mcp",
"headers": { "Authorization": "ApiKey ${input:ludo-api-key}" }
}
}
}
Gemini CLI
gemini mcp add -s user --transport http --header "Authorization: ApiKey YOUR_API_KEY" ludo https://mcp.ludo.ai/mcp
Клиенты, которые поддерживают только локальные серверы
Настройте соединение через mcp-remote (требуется Node.js). В аргументе заголовка не должно быть пробелов, а ключ нужно передать через env:
{
"mcpServers": {
"ludo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.ludo.ai/mcp", "--header", "Authorization:${LUDO_AUTH}"],
"env": { "LUDO_AUTH": "ApiKey YOUR_API_KEY" }
}
}
}
Доступные инструменты
Инструменты генерации ставят задания в очередь и сразу возвращают идентификатор задания. Поле Returns для каждого инструмента ниже описывает результат result, который вернёт getApiJob после успешного выполнения задания. Подробнее см. в разделе «Как работают вызовы генерации».
Модели
Для анимации спрайтов, переноса движения, редактирования спрайтовых листов и генерации видео можно указать необязательный параметр model. Выбирайте из доступных моделей; по умолчанию используется модель, установленная в веб-приложении Ludo.
| Модель | Назначение | Примечания |
|---|---|---|
hydra | Анимация спрайтов, ключевые кадры, перенос движения и редактирование спрайтовых листов (по умолчанию для всех четырёх задач) | Самая универсальная и мощная модель; к созданным спрайтовым листам добавляется сгенерированный звуковой эффект (audio_url, файл mp3). 3 кредита/с, минимальная длительность анимации — 3 с (минимум 9 кредитов) |
hydra-plus | Анимация спрайтов, ключевые кадры, новый ракурс (rotateSpritesheet) | Версия Hydra с более высокой детализацией; генерация занимает больше времени. Также возвращает audio_url. 4 кредита/с, минимальная длительность анимации — 3 с (минимум 12 кредитов). Для спрайтового листа, созданного с помощью hydra, такой же дополнительный проход можно выполнить через editSpritesheet с параметром edit_mode improve |
forge | Анимация спрайтов, ключевые кадры, перенос движения и редактирование спрайтовых листов | Экономичная модель для простой анимации и несложных спрайтов; при переносе движения лучше всего работает с пресетами и подходящими позами. Может потребоваться несколько попыток. 1,5 кредита/с для анимации, 2 кредита/с для переноса движения и редактирования; минимальная оплата не предусмотрена |
forge-pixel | Те же задачи, что и forge | Стоимость такая же, как у forge; предназначена для спрайтов пиксельной графики с низким разрешением |
griffin-hd | Генерация видео, создание видео по референсам и редактирование видео (по умолчанию для всех трёх задач) | Кинематографическое видео с саундтреком в любом стиле, разрешение 720p. 2 кредита/с для всех трёх задач, длительность — от 5 до 15 с. Видео в альбомной и портретной ориентации слишком велико для обработки с помощью upscaleVideo |
Модель griffin (480p) выведена из использования для генерации видео и создания видео по референсам 2026-10-27. Запросы с её указанием отклоняются; используйте griffin-hd.
Устаревшие модели — blitz, eagle, eagle-audio, tango (а также псевдоним standard) — пока поддерживаются для совместимости с существующими интеграциями, но их планируют удалить. Не используйте их для новых задач. Сервер помечает их как LEGACY в описании каждого инструмента и помещает в конец списка.
Поиск по документации (searchDocs)
Задайте вопрос по документации Ludo обычным языком и получите только несколько разделов с ответом. Например, можно узнать, как выбрать режим анимации спрайта, когда использовать Generate Before / Generate After, как работают поля, какая модель подходит для конкретной задачи, сколько она стоит и какие ограничения известны у каждого генератора. Это самый быстрый способ разобраться, как использовать функцию, прежде чем запускать генерацию, поэтому начните с поиска, а не с чтения документов целиком.
| Параметр | Обязательный | Описание |
|---|---|---|
query | Да | Вопрос на обычном языке (до 500 символов), например: «как сохранить одинаковые цвета в анимации спрайта» |
n | Нет | Максимальное количество возвращаемых разделов (1–10, по умолчанию: 3) |
Возвращает:
-
results: Массив объектов{ doc, label, section, relevance, content }, отсортированных по релевантности.contentсодержит полный текст раздела в формате markdown; значенияdocиsectionможно напрямую передать вgetDocs, чтобы открыть его повторно.relevance— оценка соответствия от 0 до 1; возвращаются только результаты с оценкой не ниже 0.6 -
message: Присутствует, только еслиresultsпуст; это означает, что в документации нет ответа на вопрос. Переформулируйте запрос или найдите нужную информацию с помощьюgetDocs
Если поиск временно недоступен, инструмент вернёт 503; в этом случае воспользуйтесь getDocs, не повторяя запрос в цикле.
Стоимость в кредитах: Бесплатно
Документация по функциям (getDocs)
Просматривайте или читайте документацию Ludo целиком. Это та же документация, которую видят пользователи веб-приложения Ludo, поэтому в ней иногда описываются кнопки, а не параметры. Однако приведённая информация применима и здесь. Чтобы ответить на конкретный вопрос, сначала используйте searchDocs.
Вызовите инструмент без параметров, чтобы получить оглавление, а затем вызовите его ещё раз с параметрами doc (и, по возможности, sections), чтобы прочитать только нужные разделы. Объём всей документации составляет около 280 000 символов, поэтому запрос полного документа без указания разделов может вернуть десятки тысяч символов.
| Параметр | Обязательный | Описание |
|---|---|---|
doc | Нет | Документ для чтения. Не указывайте параметр, чтобы получить оглавление. Допустимые значения: assistant, game-ideator, image-generator, project, account, faq, 3d-generator, video-generator, sprite-generator, audio-generator, api-mcp, game-asset-generation |
sections | Нет | Названия разделов документа doc, которые нужно вернуть. При сопоставлении не учитываются регистр, пробелы и пунктуация. Параметр можно использовать только вместе с doc |
Результат:
-
docs: массив объектов{ id, label, sections }, где каждый раздел представлен объектом{ title, content }. Полеcontentсодержит markdown и отсутствует в оглавлении -
unmatched_sections/available_sections: возвращаются только в том случае, если совпали не все запрошенные названия: здесь перечислены названия без совпадений и все допустимые названия разделов документаdoc
Если указать неизвестный doc или запросить разделы, названия которых не совпадают ни с одним допустимым, сервер вернёт ошибку 400 со списком допустимых значений. Поэтому неверно указанный параметр приведёт лишь к одному дополнительному вызову, а не к тупику.
Во время рукопожатия инициализации сервер также сообщает клиентам MCP о наличии обоих инструментов для работы с документацией через поле instructions. Поэтому модели, подключённые через клиенты, которые показывают инструкции сервера, получают указание искать информацию в документации до генерации.
Кредиты: бесплатно
Генерация изображений (createImage)
Создавайте спрайты, значки, фоны, ресурсы интерфейса и текстуры только по текстовому запросу — исходное изображение не требуется. Чтобы сохранить художественный стиль существующего изображения, используйте generateWithStyle; чтобы изменить изображение — editImage; чтобы вырезать объект — removeBackground.
| Параметр | Обязательный | Описание |
|---|---|---|
prompt | Да | Подробное описание изображения |
image_type | Да | sprite, icon, screenshot, art, asset, sprite-vfx, ui_asset, fixed_background, side_scrolling_background, texture, horizontal_tile, tile, item-icon, portrait, card-art, splash, 3d, generic |
art_style | Нет | 8-Bit, 16-Bit, 32-Bit, Hi-Bit, Low Poly, Stylized 3D, Voxel Art, Flat Design, Anime/Manga, Western Cartoon, Hand-Painted, Photorealistic 3D, Cel-Shaded и другие |
perspective | Нет | Side-Scroll, Top-Down, Isometric, First-Person, Third-Person, 2.5D |
aspect_ratio | Нет | default, ar_1_1, ar_4_3, ar_16_9, ar_9_16 |
n | Нет | Число вариантов (от 1 до 8, по умолчанию: 1) |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Кредиты: 0,5 за изображение
Редактирование изображения (editImage)
Изменяйте существующее изображение с помощью текстовых инструкций (интеллектуальное редактирование).
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение в кодировке base64 для редактирования |
prompt | Да | Описание изменений (например, «удалить фон», «сделать изображение темнее», «добавить облака в небо») |
reference_image | Нет | URL или изображение в кодировке base64, которое служит образцом для стиля или содержания |
n | Нет | Число вариантов (от 1 до 4, по умолчанию: 1) |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Кредиты: 0,5 за изображение
Генерация в заданном стиле (generateWithStyle)
Создавайте новый контент, сохраняя визуальный стиль образца.
| Параметр | Обязательный | Описание |
|---|---|---|
style_image | Да | URL или изображение в кодировке base64, используемое как образец стиля |
prompt | Да | Описание того, что нужно создать (например, «персонаж-войн», «сундук с сокровищами») |
image_type | Да | sprite, icon, screenshot, art, asset, sprite-vfx, ui_asset, fixed_background, texture, 3d, generic |
n | Нет | Число вариантов (от 1 до 4, по умолчанию: 1) |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Кредиты: 0,5 за изображение
Генерация позы (generatePose)
Создайте новую позу для существующего спрайта. Для наилучшего результата анимации используйте этот инструмент ПЕРЕД animateSprite: исходная поза должна соответствовать задуманной анимации.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение спрайта в кодировке base64 |
pose | Да | Целевая поза: Idle (Front), Idle (Back), Idle (Left Facing), Idle (Right Facing), Walk (Left), Walk (Right), Run (Left), Run (Right), Crouching, Crawling, Sitting, Attack Ready, Jump Preparation, Defending / Blocking, Flying, Sleeping или Other (с произвольным текстовым описанием в description) |
description | Нет | Дополнительные инструкции для создания позы |
n | Нет | Число вариантов (от 1 до 4, по умолчанию: 1) |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Возвращает: url, pose, motion_prompt
Пример рабочего процесса:
-
Создайте позу
Walk (Left)с помощьюgeneratePose -
Для оптимального результата анимации напрямую передайте возвращённый
motion_promptвanimateSprite
Кредиты: 0,5 за изображение
Поворот спрайта (rotateSprite)
Измените угол обзора камеры для существующего спрайта, сохранив того же персонажа и его позу. Подходит для создания разных ракурсов и направлений обзора спрайта.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение спрайта в кодировке base64 |
camera_rotation | Да | Азимут камеры в градусах: 0 (спереди), 45 (спереди справа), 90 (сбоку справа), 135 (сзади справа), 180 (сзади), -135 (сзади слева), -90 (сбоку слева), -45 (спереди слева) |
camera_elevation | Нет | Наклон камеры в градусах: 0 (на уровне глаз), 30 (сверху), 60 (под большим углом сверху). Не указывайте параметр, чтобы сохранить текущий угол наклона камеры относительно спрайта. |
n | Нет | Число вариантов (от 1 до 4, по умолчанию: 1) |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Возвращает: url, camera_rotation, camera_elevation
Кредиты: 0,5 за изображение
Удаление фона (removeBackground)
Удалите фон с одного изображения, чтобы получить объект на прозрачном фоне. Для более масштабного редактирования, а не только вырезания объекта, используйте editImage.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение в кодировке base64 |
crop | Нет | Обрезать результат по границам объекта (по умолчанию: false) |
creative_edit | Нет | Более качественный результат, который может не полностью совпадать с исходным изображением на уровне пикселей (по умолчанию: true). Установите значение false, если объект должен остаться пиксель-в-пиксель идентичным, например, если это существующий спрайт для анимации |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Возвращает: один результат с url (прозрачный PNG)
Кредиты: 0,5 за изображение
Увеличение разрешения изображения (upscaleImage)
Создайте копию изображения с разрешением до 4 раз выше. Максимальная длина большей стороны результата — 2048px. Длина большей стороны исходного изображения должна быть меньше 2048px: в противном случае запрос будет отклонён с ошибкой HTTP 400 до списания кредитов.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение в кодировке base64; длина большей стороны должна быть меньше 2048px |
request_id | Нет | Идентификатор, предоставленный клиентом для последующего получения результатов |
Возвращает: один результат с url
Кредиты: 0,5 за изображение
Создание 3D-модели (create3DModel)
Преобразует 2D-изображение в 3D-модель GLB с текстурами. При необходимости в том же вызове можно добавить риг.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение в кодировке base64, используемое как вид спереди |
model | Нет | prop (по умолчанию): недорогой вариант для обычных предметов и элементов окружения. hero: значительно более детализированная и точная модель для крупных планов; её создание занимает больше времени и стоит дороже |
back_image | Нет | Только для prop: изображение того же объекта со спины (URL или base64). Оно задаёт вид задней части модели, вместо того чтобы система создавала его самостоятельно. Для hero этот параметр не поддерживается |
texture_type | Нет | pbr (по умолчанию), simple, none |
texture_size | Нет | 1024, 2048 (по умолчанию) |
target_num_faces | Нет | Количество треугольников: от 1 000 до 200 000 (по умолчанию: 50 000) |
rig | Нет | Добавить риг модели (скелет и веса скиннинга) в том же вызове (по умолчанию: false). Используется универсальный риг, подходящий для моделей любой формы; выбрать тип рига здесь нельзя (rigModel предлагает другие варианты). Пресеты анимации и preset_id из Directional Sprites можно переназначить на этот риг, но такая возможность доступна не для всех моделей |
joint_naming | Нет | При использовании rig задаёт схему именования костей, как в rigModel (по умолчанию: smpl) |
request_id | Нет | Идентификатор, заданный клиентом для последующего получения результатов |
Возвращает: model_url (файл GLB), изображения модели с разных ракурсов и rigged
Стоимость: 4 кредита за модель с prop, 15 — с hero; добавление рига (rig) стоит 1 кредит, который списывается только в том случае, если модель возвращена с ригом
Время обработки: 60–120 секунд для prop; для hero требуется больше времени
Изображение для 3D-модели (create3DModelImage)
Создаёт изображение персонажа, подготовленное для передачи в create3DModel. Это первый этап работы с Directional Sprites в веб-интерфейсе. create3DModel преобразует переданное изображение без изменений, а этот инструмент сначала создаёт изображение для него. Можно передать запрос, собственное изображение или и то и другое: изображение будет перерисовано в виде 3D-рендера, а запрос задаст необходимые изменения. При каждом вызове изображение создаётся заново, поэтому для новой попытки вызовите инструмент ещё раз.
| Параметр | Обязательный | Описание |
|---|---|---|
prompt | Один из двух | Если изображение не передано — описание персонажа (например, «рыцарь в зелёных доспехах, в полный рост, стоит»). Если изображение передано — необязательное описание изменений (например, «добавить красный плащ и меч»). До 1 000 символов |
image | Один из двух | URL или изображение в кодировке base64. Изображение будет перерисовано в виде 3D-рендера |
request_id | Нет | Идентификатор, заданный клиентом для последующего получения результатов |
Возвращает: один результат с url, который нужно передать в параметр image инструмента create3DModel
Стоимость: 0,5 кредита за изображение
Добавление рига к 3D-модели (rigModel)
Создаёт скелет и веса скиннинга для существующей 3D-модели, чтобы её можно было анимировать. Геометрия не изменяется: результатом становится новый файл GLB с ригом. Добавьте риг к модели до вызова animate3DModel.
| Параметр | Обязательный | Описание |
|---|---|---|
model | Да | URL или файл GLB в кодировке base64, к которому нужно добавить риг |
rig_type | Нет | Стиль скелета: general (по умолчанию, подходит для любых объектов), humanoid (для персонажей в стиле аниме, самый детализированный скелет), game (классический риг игрового персонажа) или фиксированные шаблоны гуманоидов с именованными суставами: humanoid_template (22 сустава) и humanoid_template_hands (52 сустава, по пять пальцев на каждой руке). Шаблоны подходят только для персонажей с двумя руками и двумя ногами. Пресеты анимации (animate3DModelPreset) можно переназначить на любой тип рига, но такая возможность доступна не для всех моделей |
joint_naming | Нет | Схема именования распознанных суставов: smpl (по умолчанию), mixamo (автоматическое сопоставление гуманоидов в Unity), humanik (имена без префиксов для Maya/MotionBuilder/FBX), unreal (манекен UE), godot (SkeletonProfileHumanoid), rigify (Blender) или vroid (VRM). Меняются только имена, скелет остаётся прежним |
request_id | Нет | Необязательный идентификатор запроса, заданный клиентом |
Возвращает: model_url (файл GLB с ригом, в который встроены скелет и веса скиннинга), rigged (true)
Стоимость: 1 кредит за риг
Время обработки: 60–120 секунд
Анимация 3D-модели (animate3DModel)
Создаёт скелетную анимацию по текстовому описанию для модели с уже добавленным ригом (сначала добавьте риг с помощью rigModel). Качество анимации может быть нестабильным, поэтому инструмент возвращает несколько вариантов на выбор. Каждый вариант представляет собой отдельный файл GLB только с анимацией (скелет и один клип, без сетки) и видео-превью в формате mp4. Выберите подходящий вариант и объедините его с моделью в игровом движке или three.js.
| Параметр | Обязательный | Описание |
|---|---|---|
model | Да | URL или файл GLB с ригом в кодировке base64 для анимации (сначала добавьте риг с помощью rigModel) |
prompt | Да | Описание нужного движения (например, «идёт», «размахивает топором», «машет в знак приветствия») |
mode | Нет | Формат представления анимации: rot_trans (по умолчанию — вращение и перемещение каждой кости, наиболее точный вариант) или rot_only (только вращение костей и перемещение корневой кости; подходит для переназначения на другие скелеты и конвейеры движков, не поддерживающие перемещение отдельных костей) |
num_variants | Нет | Количество создаваемых вариантов анимации: от 1 до 8 (по умолчанию: 4) |
loop | Нет | Возвращать ли анимацию к исходной позе: клип воспроизводится вперёд, а затем в обратном направлении до позы покоя, образуя бесшовный цикл (по умолчанию: true). Лучше всего подходит для движений в одну сторону — например, приседания, удара или взмаха рукой. Для циклических движений, таких как ходьба, результат может выглядеть неестественно |
augment_prompt | Нет | Переформулировать запрос в подробное описание движения (по умолчанию: true) |
request_id | Нет | Необязательный идентификатор запроса, заданный клиентом |
Возвращает: animations — массив вариантов. Каждый элемент содержит clip_name, glb_url (файл GLB только с анимацией), preview_url (mp4), mode, seed, motion, fit_rmse
Стоимость: 0,5 кредита за генерацию. Одно списание покрывает все варианты; действует промо-цена
Время обработки: 60–120 секунд
Анимация 3D-модели по пресету (animate3DModelPreset)
Применяет к модели с уже добавленным ригом готовый пресет анимации с переназначением на скелет модели. В отличие от animate3DModel, здесь используется не текстовый запрос, а библиотека профессионально подготовленных клипов, поэтому инструмент возвращает ровно один клип. Пресет можно применить к ригу любого типа. Сначала добавьте риг с помощью rigModel или вызовите create3DModel с параметром rig: true. Переназначение поддерживается не для всех моделей: в случае неудачи задача завершится с ошибкой. Подходит любой идентификатор пресета из listAnimationPresets.
| Параметр | Обязательный | Описание |
|---|---|---|
model | Да | URL или файл GLB с ригом в кодировке base64 (подходит риг любого типа) |
preset_id | Да | Идентификатор пресета из listAnimationPresets |
crop_loop | Нет | Обрезать анимацию до интервала, который образует бесшовный цикл. Если не указывать параметр, включается автоматический режим: циклические движения (ходьба, ожидание) зацикливаются, а одиночные действия (прыжок, заклинание) сохраняются полностью |
in_place | Нет | Убрать суммарное перемещение модели, чтобы персонаж двигался на месте. Такой клип «на беговой дорожке» ожидает игровой движок, который сам управляет перемещением. Если не указывать параметр, используется значение, соответствующее crop_loop |
request_id | Нет | Необязательный идентификатор запроса, заданный клиентом |
Возвращает: animations — объект того же формата, что и у animate3DModel, с одним клипом, содержащим clip_name, preset_id, glb_url (файл GLB только с анимацией, имена суставов соответствуют именам в модели), preview_url (mp4), seed, motion, fit_rmse
Стоимость: 0,5 кредита за переназначение
Время обработки: 30–90 секунд
Directional Sprites
Создаёт стилизованные спрайты 3D-модели, снятые максимум с 8 направлений. Камера располагается вокруг персонажа, обращённого на юг. Все направления, запрошенные в одном вызове, обрабатываются вместе: размер кадра, масштаб и положение относительно пола будут одинаковыми, поэтому спрайты выровнены друг относительно друга. Типовой порядок работы:
-
(Необязательно) Изображение персонажа: создайте его с помощью
create3DModelImageпо текстовому запросу или передайте собственное изображение для перерисовки в виде 3D-рендера. -
Модель с ригом: вызовите
create3DModel, передав изображение иrig: true, или используйтеrigModelдля уже готовой модели. К ригу любого типа можно применить пресет анимации, однако переназначение поддерживается не для всех моделей. -
(Необязательно) Анимация — не более одной: задайте
preset_idизlistAnimationPresetsили передайтеanimation_url, полученный для этой модели с помощьюanimate3DModelPresetилиanimate3DModel. Если анимация не задана, спрайты будут показывать неподвижную позу. -
listDirectionalSpriteStyles: выберите стиль. -
previewDirectionalSprites: проверьте результат бесплатно. -
Для анимированных спрайтовых листов вызовите
createDirectionalSprites, а для неподвижных изображений —createDirectionalStills.
listDirectionalSpriteStyles
Бесплатный вызов. Возвращает styles — список стилей, каждый из которых содержит id, label, description, family, pixel, thumbnail_url, version, а также settings / advanced_settings с параметрами name, kind (тип choice, bool или color), options и default. Кроме того, возвращает доступные для выбора perspectives и directions.
previewDirectionalSprites
Несколько кадров модели в выбранном стиле для каждого запрошенного направления — чтобы оценить результат до рендеринга. Вызов синхронный, не создаёт задачу и не расходует кредиты; результат не сохраняется в ваших генерациях. Возвращает previews — по одному элементу на направление. Каждый элемент содержит frame_urls (изображения с прозрачным фоном: 4 кадра для анимированной модели и 1 для статичной), width, height, num_frames, fps и render_3d (стиль и параметры, использованные при рендеринге). На один аккаунт можно запустить только один предпросмотр одновременно: запуск нового отменяет ещё выполняющийся, и тот возвращает пустое тело ответа (HTTP 204). Принимает параметры модели, анимации, камеры и стиля, описанные ниже, а также target_frame_size (32–384, значение по умолчанию — 256).
createDirectionalSprites
| Параметр | Обязательный | Описание |
|---|---|---|
model | Да | URL или GLB в кодировке base64 (с ригом, если модель нужно анимировать) |
animation_url | Нет | Анимация для этой модели: значение glb_url из animate3DModel или animate3DModelPreset (URL или base64) |
preset_id | Нет | Пресет из listAnimationPresets, перенесённый на модель. Подходит ригам любого типа, однако перенос не всегда удаётся; в таком случае вызов возвращает ошибку |
crop_loop | Нет | Вместе с preset_id: обрезать пресет до участка, который образует бесшовный цикл |
model_animation | Нет | Название анимации, встроенной в сам GLB |
perspective | Нет | horizon, low, isometric (по умолчанию), high, top |
directions | Нет | До 8 направлений из списка: S, SW, W, NW, N, NE, E, SE (по умолчанию: ["SW"]) |
style_id | Нет | Стиль из listDirectionalSpriteStyles (по умолчанию: render_3d) |
style_params | Нет | Изменяемые параметры стиля, указанные по имени |
style_version | Нет | Зафиксировать версию стиля, например ту, которую возвращает предыдущий вызов render_3d |
target_frame_size | Нет | Размер спрайта в пикселях: 32–640 (по умолчанию: 640) |
num_frames | Нет | Количество кадров на листе: 4–100 (по умолчанию: 36) |
loop | Нет | Сэмплировать анимацию как бесшовный цикл; если параметр не указан, следовать исходной анимации |
keep_horizontal_travel / keep_vertical_travel | Нет | Сохранять горизонтальное перемещение анимации по земле (по умолчанию: выключено) / вертикальное движение (по умолчанию: включено) |
gif / individual_frames | Нет | Дополнительно возвращать каждый лист в формате GIF / кадры листа как отдельные изображения |
request_id | Нет | Идентификатор, заданный клиентом для получения результатов позднее |
Можно указать не более одного из параметров animation_url, preset_id и model_animation. Если не указан ни один из них, каждый лист будет состоять из одного кадра.
Возвращает: sheets — по одному элементу на каждое направление в запрошенном порядке. Каждый элемент содержит direction, spritesheet_url, video_url, num_frames, num_cols, num_rows, fps, render_3d, а при соответствующем запросе — gif_url / individual_frame_urls
Стоимость: 1 кредит за направление
createDirectionalStills
Модель в исходном виде: для каждого направления создаётся одно крупное изображение спрайта с прозрачным фоном, готовое к использованию в animateSprite или editImage. Принимает параметры model, perspective, directions, style_id, style_params, style_version и request_id, описанные выше.
Возвращает: images — по одному элементу на направление. Каждый элемент содержит direction, url, width, height и render_3d
Стоимость: 0,5 кредита за направление
Анимация спрайтов (animateSprite)
Создаёт анимированные спрайт-листы из статичных изображений. Используйте этот инструмент, если можете описать движение текстом. Чтобы скопировать точное движение из видео-образца или именованного пресета, используйте transferMotion. Если исходное изображение ещё не соответствует позе, с которой должна начинаться анимация, сначала примените generatePose.
| Параметр | Обязательный | Описание |
|---|---|---|
initial_image | Да | URL или изображение в кодировке base64 для начального кадра |
motion_prompt | Да | Описание анимации (например, «идёт», «спокойно дышит», «наносит удар мечом», «обеими руками создаёт огненный шар»). См. раздел Как составить запрос на анимацию |
image_type | Нет | sprite (по умолчанию), sprite-vfx, ui_asset |
frames | Нет | 4, 9, 16, 25, 36 (по умолчанию), 49, 64 |
frame_size | Нет | 0 (по умолчанию, максимальное разрешение), 32, 64, 96, 128, 192, 256, 384, -1 (увеличение изображения с помощью AI в 1,5 раза), -9 (размер исходного кадра) |
loop | Нет | Бесшовный цикл (по умолчанию: true) |
crop | Нет | Обрезать кадры по границам содержимого (по умолчанию: true). Это уменьшает размер спрайт-листов, но размеры кадров могут различаться в разных анимациях |
margin_ratio_horizontal | Нет | Горизонтальный отступ вокруг спрайта в виде доли от 0.0 до 1.0. Используется только при значении manual параметра margin_ratio_mode. Полезен для анимаций с движением в стороны, например взмахов мечом или ударов кулаком |
margin_ratio_vertical | Нет | Вертикальный отступ вокруг спрайта в виде доли от 0.0 до 1.0. Используется только при значении manual параметра margin_ratio_mode. Полезен для анимаций с движением вверх или вниз, например прыжков |
margin_ratio | Нет | Устаревший параметр: задаёт одинаковый отступ по обеим осям. Эквивалентен заданию одинакового значения для обоих параметров осей. Нельзя сочетать с параметрами отдельных осей; в противном случае вызов завершится ошибкой 400 |
margin_ratio_mode | Нет | auto (по умолчанию), manual, none |
augment_prompt | Нет | Дополнять запрос на анимацию автоматически (по умолчанию: true) |
model | Нет | hydra (по умолчанию; универсальная модель с наибольшими возможностями, генерирует звук), hydra-plus (улучшенная детализация по сравнению с hydra, но работает медленнее; также генерирует звук), forge (только для базовой анимации и простых спрайтов; может потребоваться несколько попыток), forge-pixel (пиксельная графика с низким разрешением). Устаревшие модели, не рекомендуемые для новых проектов: blitz, eagle, eagle-audio (псевдоним standard → blitz) |
duration | Нет | По умолчанию — 3 секунды. Для Hydra / Hydra+: от 3 до 5 секунд с шагом 0.5; для Forge / Forge Pixel: от 1 до 5 секунд с шагом 0.5. Если модель не поддерживает заданное значение по умолчанию, используется минимальная длительность |
final_image | Нет | Конечный кадр для интерполяции |
gif | Нет | Создать анимированный GIF (по умолчанию: false) |
individual_frames | Нет | Извлечь отдельные изображения кадров (по умолчанию: false) |
spritesheet_with_background | Нет | Дополнительно вернуть спрайт-лист с исходным фоном — до его удаления (по умолчанию: false) |
request_id | Нет | Идентификатор, заданный клиентом для получения результатов позднее |
Возвращает: spritesheet_url (спрайт-лист), video_url (анимация в формате mp4; передайте это значение в параметр video инструмента transferMotion или в параметр spritesheet_video_url инструмента createSpriteAudio), audio_url (только для hydra и hydra-plus: URL сгенерированного звукового эффекта в формате mp3, поэтому вызывать createSpriteAudio не нужно), num_frames, num_cols, num_rows, duration (длительность в секундах, необходимая для воспроизведения спрайт-листа с исходной скоростью), а при соответствующем запросе — gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls
Стоимость: ставка × длительность в секундах. Hydra: 3 кредита/с (минимум 3 с, то есть 9 кредитов; значение по умолчанию 3 с — 9 кредитов); Hydra+: 4 кредита/с (минимум 3 с, то есть 12 кредитов); Forge и Forge Pixel: 1,5 кредита/с, без минимальной стоимости (3 с — 4,5 кредита). Устаревшие модели: Blitz — 1,9 кредита/с, Eagle — 2,6 кредита/с, Eagle with Audio — 3,1 кредита/с; для всех минимальная стоимость составляет 4 кредита.
Время обработки: 30–90 секунд
Как составить запрос на анимацию
Применяется к animateSprite и animateSpriteKeyframes.
-
Точно и однозначно опишите, что должен делать персонаж. Можно задавать конкретные и сложные действия — упрощать их не нужно.
-
Не перегружайте описание деталями: их избыток может ухудшить анимацию. Укажите действие, которое уже известно модели, вместо того чтобы разбивать его на отдельные шаги: «идёт», а не «перемещает левую ногу вперёд, затем правую».
-
Не повторяйте то, что уже показано на изображении или задано ключевыми кадрами: персонажа, его снаряжение, художественный стиль, фон, освещение и камеру. Количество кадров и длительность задавайте с помощью параметров
framesиduration. -
Отрицательные формулировки («без фона», «не двигать камеру», «без оружия») работают только с
hydraиhydra-plus. Дляforge,forge-pixelи устаревших моделей они дают обратный эффект: упоминание нежелательного объекта повышает вероятность его появления. Для этих моделей указывайте только то, что должно происходить.
Анимация по ключевым кадрам (animateSpriteKeyframes)
Анимирует спрайт по трём фиксированным ключевым кадрам (initial_image, middle_image, final_image) и создаёт спрайт-лист с интерполяцией кадров в заданном порядке. Работает на hydra (по умолчанию), hydra-plus, forge и forge-pixel — моделях, которые поддерживают средний ключевой кадр. Описание движения указывать необязательно: если его не задать, движение будет определяться только ключевыми кадрами. Если нужны только начальный и конечный кадры, ту же задачу решит animateSprite с параметром final_image.
| Параметр | Обязательный | Описание |
|---|---|---|
initial_image | Нет* | URL или изображение в формате base64 для первого ключевого кадра. *Необходимо указать хотя бы один из параметров initial_image или middle_image (final_image без других кадров не принимается) |
middle_image | Нет* | URL или изображение в формате base64 для среднего ключевого кадра, через который проходит анимация |
final_image | Нет | URL или изображение в формате base64 для конечного ключевого кадра |
motion_prompt | Нет | Необязательное описание анимации (например, «рубящий удар»); если его не указать, движение будет определяться ключевыми кадрами. См. раздел Как составить описание движения |
image_type | Нет | sprite (по умолчанию), sprite-vfx, ui_asset |
model | Нет | hydra (по умолчанию; генерирует аудио), hydra-plus (версия hydra с более высокой детализацией; также генерирует аудио), forge или forge-pixel для пиксельной графики |
frames | Нет | 4, 9, 16, 25, 36 (по умолчанию), 49, 64 |
frame_size | Нет | 0 (по умолчанию, максимальное разрешение), 32, 64, 96, 128, 192, 256, 384, -1 (увеличение разрешения с помощью AI в 1,5 раза), -9 (подогнать под размер входного кадра) |
loop | Нет | Создать бесшовный цикл (по умолчанию: true) |
crop | Нет | Обрезать кадры по содержимому (по умолчанию: true); спрайт-листы становятся меньше, но размеры кадров могут различаться |
margin_ratio_horizontal | Нет | Горизонтальный отступ вокруг спрайта в виде коэффициента от 0.0 до 1.0 (используется только при значении manual для margin_ratio_mode) |
margin_ratio_vertical | Нет | Вертикальный отступ вокруг спрайта в виде коэффициента от 0.0 до 1.0 (используется только при значении manual для margin_ratio_mode) |
margin_ratio | Нет | Устаревший параметр — одинаковый отступ по обеим осям; нельзя использовать вместе с параметрами для отдельных осей (запрос завершится ошибкой 400) |
margin_ratio_mode | Нет | auto (по умолчанию), manual, none |
augment_prompt | Нет | Дополнять описание движения в фоновом режиме (по умолчанию: true) |
duration | Нет | По умолчанию — 3 с. Hydra / Hydra+: от 3 до 5 с; Forge / Forge Pixel: от 1 до 5 с с шагом 0.5. Для трёх ключевых кадров требуется достаточно времени: при длительности 1 с начальный переход сжимается и исчезает |
gif | Нет | Создать анимированный GIF (по умолчанию: false) |
individual_frames | Нет | Извлечь изображения отдельных кадров (по умолчанию: false) |
spritesheet_with_background | Нет | Также вернуть спрайт-лист с исходным фоном, до его удаления (по умолчанию: false) |
request_id | Нет | Идентификатор, заданный клиентом, для получения результатов позднее |
Возвращает: данные той же структуры, что и animateSprite (spritesheet_url, video_url, audio_url для hydra и hydra-plus, gif_url, num_frames, num_cols, num_rows, duration, ...)
Стоимость в кредитах: такая же, как у animateSprite: Hydra — 3 кредита в секунду (3 с = 9); Hydra+ — 4 кредита в секунду (3 с = 12); Forge / Forge Pixel — 1,5 кредита в секунду, без минимальной стоимости (1 с = 1,5; 3 с = 4,5; 4 с = 6)
Время обработки: 30–90 секунд
Готовые анимации (listAnimationPresets)
Список доступных готовых анимаций, которые можно использовать в transferMotion (для спрайта) и animate3DModelPreset (для подготовленной 3D-модели). Возвращает анимации, ракурсы и направления; URL видео не предоставляются.
Возвращает:
-
animations: массив готовых анимаций с полямиid,name,category,description,durationиpreview_url; любую из них можно перенести на подготовленную 3D-модель с помощьюanimate3DModelPresetили использовать как значениеpreset_idдля Directional Sprites -
perspectives: массив с полямиid,name,description(все анимации поддерживают все ракурсы) -
directions:["N", "NE", "E", "SE", "S", "SW", "W", "NW"](все анимации поддерживают все направления)
Стоимость в кредитах: бесплатно
Перенос движения (transferMotion)
Переносит движение из видео или готовой анимации на статичный спрайт и создаёт анимированный спрайт-лист. Используйте этот инструмент, если нужно точно воспроизвести движение: стандартный цикл ходьбы или атаки из listAnimationPresets либо собственный видеоклип. Чтобы описать движение текстом, используйте animateSprite.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или изображение спрайта в формате base64 |
video | Нет | URL видео, используемого как источник движения: video_url спрайт-листа, созданного с помощью animateSprite, или собственный видеоклип. Лучше всего подходят видео длительностью до 4 секунд. Необходимо указать либо video, либо preset_id вместе с perspective и direction; если переданы оба варианта, используется видео |
preset_id | Нет | Идентификатор готовой анимации из listAnimationPresets, используемой вместо URL видео. При использовании готовой анимации необходимо указать perspective и direction |
direction | Нет | Направление, в котором обращён персонаж, заданное стороной света: N, NE, E, SE, S, SW, W, NW. Обязательно при использовании готовой анимации |
perspective | Нет | Ракурс камеры для готовой анимации; набор значений одинаков для всех анимаций: high (тактический, крутой вид сверху), horizon (вид сбоку на уровне глаз), isometric (диагональный вид сверху с глубиной), low (героический ракурс снизу), top (вид строго сверху). Обязательно при использовании готовой анимации |
frames | Нет | 4, 9, 16, 25, 36 (по умолчанию), 49, 64 |
frame_size | Нет | 0 (по умолчанию, максимальное разрешение), 32, 64, 96, 128, 192, 256, 384 |
loop | Нет | Обрезать анимацию для создания бесшовного цикла (по умолчанию: true) |
crop | Нет | Обрезать кадры по содержимому (по умолчанию: true) |
margin_ratio_horizontal | Нет | Горизонтальный отступ вокруг спрайта (0.0–1.0). Полезен для анимаций с движением в стороны, например ударов мечом или кулаком |
margin_ratio_vertical | Нет | Вертикальный отступ вокруг спрайта (0.0–1.0). Полезен для анимаций с движением вверх или вниз, например прыжков |
margin_ratio | Нет | Устаревший параметр — одинаковый отступ по обеим осям (0.0–1.0; по умолчанию 0.15, если отступ не задан). Нельзя использовать вместе с параметрами для отдельных осей (запрос завершится ошибкой 400) |
margin_ratio_mode | Нет | manual (по умолчанию), none |
gif | Нет | Создать анимированный GIF (по умолчанию: false) |
individual_frames | Нет | Извлечь изображения отдельных кадров (по умолчанию: false) |
spritesheet_with_background | Нет | Также вернуть спрайт-лист с исходным фоном, до его удаления (по умолчанию: false) |
model | Нет | hydra (по умолчанию; наиболее функциональная модель, генерирует аудио), forge (дешевле; подходит для простых движений, лучше всего работает с готовыми анимациями и соответствующими позами), forge-pixel (пиксельная графика). Устаревшая модель, не рекомендуется для новых задач: tango |
duration | Нет | Длительность анимации в секундах. Если параметр не задан, длительность составит 1,5 с, если модель поддерживает такое значение, а в противном случае будет установлена минимальная длительность модели — например, 3 с для hydra (модель по умолчанию). Hydra: от 3 до 5 с с шагом 0.5; Forge / Forge Pixel: от 1 до 5 с. Более длинный эталонный видеоклип или готовая анимация сжимаются до заданной длительности. Чтобы сохранить исходный темп, передайте значение duration из параметров готовой анимации |
request_id | Нет | Идентификатор, заданный клиентом, для получения результатов позднее |
Возвращает: данные той же структуры, что и animateSprite (spritesheet_url, video_url, audio_url для hydra, gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls, num_frames, num_cols, num_rows, duration)
Стоимость в кредитах: тариф за секунду × длительность. Hydra (по умолчанию): 3 кредита в секунду (по умолчанию 3 с = 9); Forge / Forge Pixel: 2 кредита в секунду, без минимальной стоимости (1,5 с = 3; 3 с = 6). Устаревшая Tango: 4 кредита в секунду, минимум 4 кредита. Длительность результата соответствует длительности эталонного клипа; плата никогда не взимается за время сверх запрошенного
Редактирование спрайт-листа (editSpritesheet)
Отредактируйте ранее созданный спрайт-лист: задайте новую инструкцию для анимации, расширьте изображение за пределы кадра (уменьшите масштаб), исправьте неудачный цикл или повторно отрисуйте лист hydra с большей детализацией (improve). Передайте spritesheet_url, полученный от animateSprite, animateSpriteKeyframes, transferMotion или в результате предыдущего редактирования. Это должен быть спрайт-лист, созданный вами за последние 7 дней; внешние URL не принимаются. Не указывайте duration, frames, frame_size, crop и model, чтобы сохранить значения исходного спрайт-листа.
| Параметр | Обязательный | Описание |
|---|---|---|
spritesheet_url | Да | URL спрайт-листа, созданного вами за последние 7 дней |
edit_mode | Нет | prompt (по умолчанию) — задать новую инструкцию для анимации; outpaint — расширить изображение за пределы кадра; fix_loop — исправить неудачный цикл; improve — повторно отрисовать с большей детализацией (при генерации выполняется дополнительный проход hydra-plus). Для improve подходит только спрайт-лист, созданный с помощью hydra: для любого другого источника будет возвращена ошибка 400, в том числе для уже улучшенного листа, а также для листа после исправления цикла или расширения за пределы кадра |
prompt | Нет | Инструкция по редактированию. Обязательна для режима prompt, необязательна для outpaint, не принимается для fix_loop и improve |
images | Нет | До 5 референсных изображений (URL или base64), которые помогут выполнить редактирование |
duration | Нет | Длительность результата в секундах (зависит от модели, как и для animateSprite). Не указывайте, чтобы сохранить длительность исходного спрайт-листа. Не влияет на стоимость fix_loop, outpaint и improve: они тарифицируются по длительности видео исходного спрайт-листа |
model | Нет | hydra (по умолчанию), forge, forge-pixel. Не указывайте, чтобы сохранить модель исходного спрайт-листа. Используется только в режиме prompt; outpaint, fix_loop и improve выполняются по фиксированному сценарию и игнорируют этот параметр |
crop | Нет | Обрезать кадры по содержимому. Не указывайте, чтобы сохранить настройку исходного спрайт-листа |
loop | Нет | Обрезать анимацию для создания бесшовного цикла (по умолчанию: true) |
frames | Нет | Количество кадров в результирующем спрайт-листе: 4, 9, 16, 25, 36, 49, 64. По умолчанию используется количество кадров исходного спрайт-листа |
frame_size | Нет | Размер кадра в пикселях: от 32 до 384 или 0 для максимального разрешения. По умолчанию используется размер кадра исходного спрайт-листа |
gif | Нет | Создать анимированный GIF (по умолчанию: false) |
individual_frames | Нет | Извлечь отдельные изображения кадров (по умолчанию: false) |
spritesheet_with_background | Нет | Также вернуть спрайт-лист с исходным фоном (по умолчанию: false) |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Возвращает: данные в том же формате, что и animateSprite (spritesheet_url, video_url, gif_url, num_frames, num_cols, num_rows, ...). Новая аудиодорожка создаётся только при редактировании в режиме prompt с hydra; для fix_loop, outpaint и improve сохраняется исходный audio_url, если он был у спрайт-листа
Стоимость: fix_loop, outpaint и improve — фиксированная стоимость 1 кредит за секунду результата; кредит резервируется с ограничением по длительности исходного видео спрайт-листа, минимальной стоимости нет, модель не учитывается (лист длительностью 3 с стоит 3 кредита независимо от переданного duration). Редактирование в режиме prompt тарифицируется в зависимости от модели: Hydra — 3 кредита/с (3 с = 9 кредитов), Forge / Forge Pixel — 2 кредита/с, минимальной стоимости нет (3 с = 6 кредитов)
Звуковой эффект для спрайт-листа (createSpriteAudio)
Создайте звуковой эффект для ранее сгенерированной анимации спрайт-листа. Спрайт-листы, созданные с помощью hydra, уже содержат audio_url, поэтому вызывайте этот инструмент для результатов forge / forge-pixel или чтобы заменить звук, созданный hydra.
| Параметр | Обязательный | Описание |
|---|---|---|
spritesheet_video_url | Да | video_url, полученный от animateSprite, animateSpriteKeyframes, transferMotion или editSpritesheet. Он должен принадлежать спрайт-листу, созданному вами за последние 7 дней |
prompt | Нет | Описание желаемого звука, например: "металлический взмах меча со свистом" |
request_id | Нет | Идентификатор, заданный клиентом, для повторного поиска задачи; он не должен совпадать с идентификатором, использованным для другой генерации |
Возвращает: url созданного аудиофайла. Аудио также прикрепляется к спрайт-листу и отображается как audio_url для соответствующего элемента в listGenerations
Стоимость: 3 кредита за вызов
Генерация видео (createVideo)
Создайте короткое видео на основе исходного изображения и текстового описания движения (image-to-video). Исходное изображение image обязательно: чтобы создать видео только по тексту, сначала вызовите createImage, а затем анимируйте полученное изображение либо используйте createVideoFromReferences. Текущая модель создаёт звуковую дорожку, поэтому отдельный этап генерации аудио не требуется.
| Параметр | Обязательный | Описание |
|---|---|---|
image | Да | URL или base64 начального кадра |
prompt | Да | Описание движения, например: "камера приближается", "персонаж идёт вперёд" |
duration | Нет | По умолчанию — 5 с. Для Griffin HD: от 5 до 15 с с шагом 1 с |
model | Нет | griffin-hd (по умолчанию; 720p, со звуковой дорожкой). Устаревшие модели, не рекомендуемые для новых задач: blitz, eagle, eagle-audio (псевдоним standard → blitz) |
final_image | Нет | Конечный кадр для интерполяции |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Возвращает: url, duration, has_audio
Стоимость: тариф × количество секунд. Griffin HD — 2 кредита/с (стандартные 5 с = 10 кредитов). Устаревшие модели: Blitz — 1 кредит/с, Eagle — 1,3 кредита/с, Eagle with Audio — 1,8 кредита/с.
Видео по референсам (createVideoFromReferences)
Создайте видео по 1–5 референсным изображениям и текстовому описанию. В отличие от createVideo, который анимирует одно исходное изображение, этот инструмент формирует новую сцену, используя персонажей, объекты и стиль с референсов.
| Параметр | Обязательный | Описание |
|---|---|---|
prompt | Да | Текстовое описание видео, которое нужно создать |
images | Да | От 1 до 5 референсных изображений (URL или base64) |
duration | Нет | Длительность видео в секундах: от 5 до 15 (по умолчанию — 5) |
model | Нет | griffin-hd (по умолчанию; 720p, со звуковой дорожкой). Устаревшие модели, не рекомендуемые для новых задач: eagle, eagle-audio |
aspect_ratio | Нет | default (модель выбирает самостоятельно), ar_1_1, ar_16_9, ar_9_16, ar_4_3, ar_3_4, ar_21_9 |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Возвращает: url, duration, has_audio
Стоимость: тариф × количество секунд, как и для createVideo: Griffin HD — 2 кредита/с (стандартные 5 с = 10 кредитов). Устаревшие модели: Eagle — 1,5 кредита/с, Eagle with Audio — 2 кредита/с.
Редактирование видео (editVideo)
Отредактируйте ранее созданное видео с помощью текстового описания и, при необходимости, референсных изображений (video-to-video). Передайте url, полученный от createVideo, createVideoFromReferences или в результате предыдущего редактирования. Это должно быть видео, созданное вами за последние 7 дней; внешние URL не принимаются.
| Параметр | Обязательный | Описание |
|---|---|---|
video | Да | URL видео, созданного вами за последние 7 дней |
prompt | Да | Инструкция с описанием желаемого изменения |
images | Нет | До 5 референсных изображений (URL или base64), которые помогут выполнить редактирование |
duration | Нет | Длительность результата в секундах: от 5 до 15. Не указывайте, чтобы сохранить длительность исходного видео |
model | Нет | griffin-hd (по умолчанию; 720p, со звуковой дорожкой). Устаревшая модель, не рекомендуемая для новых задач: eagle |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Возвращает: url, duration, has_audio
Стоимость: Griffin HD — 2 кредита/с (5 с = 10 кредитов)
Увеличение разрешения видео (upscaleVideo)
Увеличьте разрешение ранее созданного видео вдвое (2x). Передайте url, полученный от createVideo, createVideoFromReferences или editVideo. Это должно быть видео, созданное вами за последние 7 дней; внешние URL не принимаются. Обе стороны исходного видео должны быть меньше 960 пикселей: альбомное и портретное видео в 720p, созданное с помощью griffin-hd, превышает это ограничение, поэтому видео, созданное текущей моделью, подходит только в квадратном формате. Если исходное видео слишком большое, задача завершится ошибкой, а зарезервированные кредиты будут возвращены.
| Параметр | Обязательный | Описание |
|---|---|---|
video | Да | URL видео, созданного вами за последние 7 дней; обе стороны должны быть меньше 960 пикселей |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Возвращает: url (ширина и высота увеличены вдвое, длительность не меняется), duration, has_audio
Стоимость: фиксированный тариф, зависящий от длительности и не зависящий от модели: 0,2 кредита/с (5 с = 1 кредит)
Генерация звуковых эффектов (createSoundEffect)
Создавайте игровые звуковые эффекты по текстовым описаниям.
| Параметр | Обязательный | Описание |
|---|---|---|
description | Да | Описание звука, например: "выстрел лазерного оружия", "шаги по гравию", "подбор монеты" |
duration | Нет | От 0 до 10 секунд (0 — автоматический выбор длительности) |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 2 кредита за звук
Создание звукового окружения (createAmbiance)
Создавайте звуковые ландшафты и фоновые атмосферы по текстовому описанию.
| Параметр | Обязательный | Описание |
|---|---|---|
description | Да | Описание звукового окружения (например, «ветреный лес в сумерках», «оживлённый средневековый рынок», «гул двигателя космического корабля») |
duration | Нет | Длительность в секундах (0 — автоматически, на основе описания) |
loop | Нет | Создать атмосферу с бесшовным зацикливанием (по умолчанию: true) |
augment_prompt | Нет | Автоматически дополнить запрос (по умолчанию: true) |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 2 кредита за генерацию
Создание музыки (createMusic)
Создавайте фоновую музыку и музыкальные темы.
| Параметр | Обязательный | Описание |
|---|---|---|
description | Да | Описание музыки (например, «эпическая оркестровая тема для битвы», «спокойная мелодия на фортепиано», «8-битная чиптюн-композиция») |
lyrics | Нет | Текст песни для вокальных композиций |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 3 кредита за трек
Преобразование аудио (createAudioTransform)
Создавайте ремикс или преобразуйте существующий аудиофрагмент с помощью текстового запроса.
| Параметр | Обязательный | Описание |
|---|---|---|
sample | Да | URL или аудиофрагмент в кодировке base64 для создания ремикса (максимум 15 МБ) |
prompt | Да | Описание желаемого ремикса (например, «придай звучанию стиль синтвейва 80-х») |
duration | Нет | Длительность в секундах: 0 (автоматически, как у исходного файла) или от 10 до 180 с шагом 10 |
modification_strength | Нет | Степень изменения исходного аудио от 0 до 1 (по умолчанию: 0.6; значение 0 означает минимальные отличия от оригинала) |
augment_prompt | Нет | Автоматически дополнить запрос (по умолчанию: true) |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 3 кредита за генерацию
Создание голоса (createVoice)
Создавайте уникальные голоса персонажей.
| Параметр | Обязательный | Описание |
|---|---|---|
voice_description | Да | Описание персонажа (например, «хриплый голос пожилого воина», «жизнерадостный голос юной девушки») |
text | Да | Текст для озвучивания (не более 200 символов) |
type | Нет | human (по умолчанию) или non-human |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 1 кредит за голос
Преобразование текста в речь (createSpeech)
Клонируйте голос по аудиофрагменту.
| Параметр | Обязательный | Описание |
|---|---|---|
text | Да | Текст для озвучивания (не более 1000 символов) |
sample | Да | URL или аудиофрагмент в кодировке base64 для клонирования голоса |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 1 кредит за генерацию
Преобразование текста в речь с предустановленным голосом (createSpeechPreset)
Используйте предустановленные голоса для преобразования текста в речь.
| Параметр | Обязательный | Описание |
|---|---|---|
text | Да | Текст для озвучивания (не более 1000 символов) |
voice_preset_id | Да | Serious woman, Wise woman, Calm woman, Patient man, Determined man, Deep voice man, Teen boy, Sweet girl и другие |
emotion | Нет | Default, Happy, Sad, Angry, Fearful, Surprised, Neutral |
language | Нет | auto, English, Spanish, French, German, Japanese, Korean и другие |
request_id | Нет | Идентификатор, заданный клиентом, для последующего получения результатов |
Стоимость: 1 кредит за генерацию
Проверка задачи (getApiJob)
Проверяйте статус задачи генерации, созданной любым инструментом. Каждая задача возвращает {id, status}. Передавайте этот идентификатор в getApiJob, пока значение status не станет succeeded (затем прочитайте result, структура которого точно соответствует описанному для инструмента формату вывода) или failed (затем прочитайте error).
| Параметр | Обязательный | Описание |
|---|---|---|
id | Да | Идентификатор задачи, возвращённый инструментом генерации |
wait | Нет | Время ожидания в секундах при длительном опросе до наступления конечного состояния (от 0 до 60; по умолчанию: 0). Если задан wait, вызов остаётся открытым и возвращает результат сразу после завершения задачи |
Результат: id, status (queued, running, succeeded, failed, canceled), result при успешном выполнении, error ({code, subcode, message, retriable}) при ошибке, а также poll_after_ms для промежуточных ответов. Перед следующим запросом подождите не меньше указанного времени. Обычно генерация завершается за несколько минут; если задача остаётся в очереди более 15 минут, её можно отменить и отправить повторно.
Стоимость: бесплатно
Список задач (listApiJobs)
Получите список запущенных вами задач генерации через API или MCP, начиная с самых новых. Задачи из веб-приложения не включаются.
| Параметр | Обязательный | Описание |
|---|---|---|
status | Нет | Статусы для включения в список, разделённые запятыми (queued, running, succeeded, failed, canceled). По умолчанию включаются все |
limit | Нет | Максимальное количество задач в ответе (по умолчанию: 50, максимум: 100) |
Результат: массив объектов задач с полями id, status и временными метками
Стоимость: бесплатно
Отмена задачи (cancelApiJob)
Отмените задачу, которая ещё находится в очереди, и получите возврат потраченных на неё кредитов. Уже выполняющиеся задачи отменить нельзя: вызов завершится с ошибкой 409.
| Параметр | Обязательный | Описание |
|---|---|---|
id | Да | Идентификатор задачи для отмены |
Результат: отменённая задача
Стоимость: бесплатно; кредиты за задачу, находившуюся в очереди, возвращаются
История генераций (listGenerations)
Просматривайте историю генераций через API и веб-студию Ludo с фильтрацией, текстовым поиском и постраничной навигацией. Этот инструмент заменяет отдельные инструменты получения результатов по типам (getImageResults, getSpriteResults, getVideoResults, getAudioResults, get3DModelResults): они удалены из MCP и объявлены устаревшими в REST API.
| Параметр | Обязательный | Описание |
|---|---|---|
type | Да | image, spritesheet, video, audio, 3d |
source | Нет | api — ваши генерации через API/MCP за последние 7 дней; web — генерации из веб-студии без ограничения по времени; all — все источники (по умолчанию) |
search | Нет | Полнотекстовый поиск. Каждое слово, разделённое пробелом, должно совпадать с тегами или одним из текстовых полей элемента (prompt, hints, style, label и др.). Например, запрос «dwarf axe» оставит элементы, соответствующие обоим словам |
request_id | Нет | Возвращать только элементы, помеченные этим request_id при генерации |
date_from | Нет | Возвращать только элементы, созданные в это время или позднее (время в unix-секундах) |
date_to | Нет | Возвращать только элементы, созданные в это время или раньше (время в unix-секундах) |
page_size | Нет | Количество элементов на странице: от 1 до 100 (по умолчанию: 20) |
page_number | Нет | Номер страницы, начиная с 1 (по умолчанию: 1) |
Результат: items, page, page_size, has_more. Если has_more имеет значение true, продолжайте запрашивать следующие страницы.
Стоимость: бесплатно
Учётная запись (getAccount)
Просмотрите баланс кредитов, тарифный план и настройки автоматического пополнения. Проверяйте их перед дорогостоящей генерацией, чтобы не ждать ошибки 402. Параметры не требуются.
Результат:
-
credits:-
available: количество кредитов, доступных для генераций прямо сейчас (plan_credits+extra-used). -
resets_at: время следующего пополнения кредитов по тарифному плану (unix-секунды). -
team_pool: значение true означает, что баланс является общим для команды. -
paused: значение true означает, что подписка приостановлена. -
grace_until: указывает, до какого момента можно использовать оставшиеся кредиты после окончания подписки.
-
-
plan: содержитnameиapi_access. -
auto_topup: содержитenabled,thresholdиcredits. Для участников команды значение равно null, так как настройками управляет владелец команды. -
billing_url: ссылка для покупки кредитов, смены тарифного плана или настройки автоматического пополнения. Эти изменения выполняются в веб-приложении, а не через API.
Стоимость: бесплатно
Отправка отзыва (submitApiFeedback)
Сообщайте команде Ludo о проблемах с самим Ludo API. Используйте этот инструмент только для ошибок API (ошибки, неудачные или зависшие задачи, сбои, ответы, не соответствующие документации) и ограничений API (нужный вам параметр, операция или формат, который API не поддерживает и для которого не удалось найти обходное решение). Не сообщайте через этот инструмент об ограничениях модели или качестве результата: если изображение, спрайт, анимация, 3D-модель, видео или звук выглядят неправильно, игнорируют часть запроса, содержат артефакты или не соответствуют вашим ожиданиям, это не ошибка API. Вместо этого попробуйте изменить запрос, модель или настройки. Опишите, что вы пытались сделать и что пошло не так. Отправляйте отдельное сообщение для каждой проблемы, не включайте личные данные, секреты и содержимое файлов. Если вы действуете как агент, сообщите пользователю, что именно вы отправили.
| Параметр | Обязательный | Описание |
|---|---|---|
category | Да | bug, limitation, feature_request, praise или other. Неправильный результат генерации связан с ограничениями модели, а не с ошибкой: не сообщайте о нём |
message | Да | Что вы пытались сделать, что произошло и что могло бы помочь (не более 4000 символов) |
operation | Нет | Инструмент, к которому относится отзыв, например animateSprite |
job_id | Нет | Идентификатор связанной задачи, если она есть |
agent | Нет | Агент или приложение, отправляющее отзыв, например Claude Code |
Результат: ok и идентификатор отзыва id
Стоимость: бесплатно
Как работают вызовы генерации
Каждая генерация выполняется в очереди задач, и в MCP все инструменты генерации работают асинхронно. Вызов генерации сразу возвращает {id, status: "queued"}, не дожидаясь завершения задачи. Благодаря этому соединение не остаётся открытым, пока работает GPU, а транспорт MCP не может завершить ожидание по тайм-ауту во время генерации. Чтобы получить результат, используйте getApiJob. У инструментов MCP нет параметра async — его не нужно задавать.
(REST API работает так же, если вы вызываете его напрямую, а не через MCP: по умолчанию запросы выполняются асинхронно и возвращают 202 с идентификатором задачи. Синхронные ответы считаются устаревшими, но передача async: false в запросе по-прежнему включает их, и эта возможность будет поддерживаться без ограничения срока.)
Получение результата
{ "id": "job_abc123", "status": "queued" }
Long-poll until it finishes (up to 60s per call), then read result
getApiJob with id="job_abc123", wait=30 -> { "id": "job_abc123", "status": "succeeded", "result": { "spritesheet_url": "...", ... } }">
# Submit the work, get a job id straight back
animateSprite with initial_image="url", motion_prompt="walking"
-> { "id": "job_abc123", "status": "queued" }
# Long-poll until it finishes (up to 60s per call), then read result
getApiJob with id="job_abc123", wait=30
-> { "id": "job_abc123", "status": "succeeded", "result": { "spritesheet_url": "...", ... } }
result точно соответствует ответу, описанному для инструмента. Если задача завершилась с ошибкой, вместо него прочитайте error. Если параметр wait не задан, проверяйте состояние задачи каждые несколько секунд и учитывайте значение poll_after_ms, указанное в ответах о незавершённых задачах. Используйте listApiJobs, чтобы посмотреть список выполняющихся задач, а cancelApiJob — чтобы отменить ещё не запущенную задачу и вернуть потраченные на неё кредиты.
Списание кредитов
Кредиты резервируются после принятия задачи. Для инструментов с оплатой за длительность (спрайты и видео) итоговая сумма рассчитывается по формуле max(ставка × длительность результата в секундах, минимальная стоимость модели) и не превышает стоимость запрошенной длительности. Разница возвращается после завершения задачи. Если задача завершается с ошибкой или вы отменяете её, пока она находится в очереди, все кредиты возвращаются. В строке Credits выше для каждого инструмента указаны ставка и минимальная стоимость; сервер также сообщает условия один раз в поле instructions.
Ограничения на использование
-
Не более 50 генераций в очереди или в процессе выполнения на аккаунт. При превышении лимита возвращается
429с кодомPENDING_JOBS_LIMIT. Дождитесь завершения задач и отправьте запросы снова. -
Не более 150 запросов за 5 минут к конечным точкам чтения (состояние и список задач, история генераций, сведения об аккаунте и документация по функциям) для каждого API key. В ответе
429указываетсяRetry-After. -
Не более 60 запросов за 5 минут и 1 000 запросов в день к поиску по документации (
searchDocs) для каждого API key.
Как найти результаты позже
Каждый инструмент генерации также принимает необязательный параметр request_id. С его помощью можно пометить результат и найти его позже, например в другом сеансе:
# Tag a generation
animateSprite with request_id="my-anim-001", initial_image="url", motion_prompt="walking"
# Later, look it up again
listGenerations with type="spritesheet", request_id="my-anim-001"
listGenerations — универсальный инструмент для просмотра истории. Фильтруйте результаты по type, источнику (api, web или all), тексту поиска или дате и просматривайте их постранично. Результаты, созданные через API, доступны в течение 7 дней.
Срок действия URL ресурсов
Все URL созданных ресурсов (изображений, спрайтов, видео, аудио и 3D-моделей) ведут на ссылки Google Cloud Storage, срок действия которых истекает через 7 дней. Если ресурс должен быть доступен дольше, особенно если он предназначен для использования в производственной среде, сразу скачайте и сохраните его локально или повторно загрузите в постоянное хранилище. Не используйте возвращённые URL как постоянные ссылки.
Сервер также сообщает об этом MCP-клиентам через поле instructions во время рукопожатия initialize. Поэтому модели, подключённые через клиенты, которые отображают инструкции сервера, будут получать это напоминание автоматически.
Примеры запросов
Создание игровых ресурсов
Create a pixel art knight character with sword and shield, side view, 16-bit style
Generate an isometric treasure chest icon for a mobile RPG
Create a low-poly stylized tree for a casual mobile game
Анимация
Animate this character with a smooth walking cycle, 16 frames
Create an idle breathing animation for this character sprite
Rig this 3D character using Mixamo joint names, then apply a walk animation preset to it
Animate this fire sprite as a looping VFX effect
Аудио
Create a satisfying coin pickup sound effect for a platformer
Generate an epic orchestral boss battle theme, intense and dramatic
Create a voice for a wise old wizard saying "The journey begins now"
Документация API
Полная документация API со всеми параметрами и форматами ответов: Документация API на api.ludo.ai
Поддержка
Лицензия
Проприетарная лицензия. Условия использования см. на странице Условия использования ludo.ai.