API ВЕГА
English

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.