Ludo AI Game Assets

Ludo AI MCP 服务

通过 模型上下文协议（MCP） 使用 AI 生成游戏资源。

功能

类别	功能
图像	精灵、图标、截图、背景、UI 资源、纹理、背景移除、放大
3D 模型	可用于 3D 模型的角色图像（根据提示词生成，或将你自己的图像重新绘制为 3D 渲染图），将 2D 图像转换为带 PBR 纹理的 GLB 模型（道具或细节更丰富的主角模型，也可在同一次调用中绑定骨骼），自动绑定模型（骨架 + 蒙皮权重，采用适用于游戏引擎的关节命名），文本驱动的骨骼动画，将精选动画预设重定向到已绑定骨骼的模型
方向精灵	将 3D 模型渲染为风格化精灵，最多支持 8 个对齐方向；风格从像素艺术到绘画风格、3D 渲染均可；可使用预设或自己的片段进行动画制作，并可在渲染前免费预览
动画	从静态精灵生成动画精灵表（4-64 帧），通过最多三帧固定关键帧制作动画，从视频或预设迁移动作，编辑精灵表（重新输入提示词、扩展画布、修复循环、以更精细的细节重新渲染），为精灵表生成音效
视频	根据图像或参考图像生成短视频（5-15 秒，带配乐），由提示词驱动的视频编辑，2x 放大
音频	音效、背景音乐、角色语音、TTS
任务与历史记录	异步任务队列：提交、轮询或长轮询、列出和取消任务（排队中的任务会退还额度），以及跨 API 和 Web 应用分页查看生成历史记录
账户	额度余额、套餐和自动充值设置，可在高成本生成前查看
文档	生成前搜索或阅读 Ludo 自带的功能指南：动画模式、模型选择、边距、已知限制
反馈	向 Ludo 团队报告限制、错误或缺失的功能

快速开始

1. 获取 API 密钥

在 ludo.ai 注册，并从 app.ludo.ai 获取 API 密钥。

2. 配置 MCP 客户端

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

Cursor

在 Cursor 偏好设置中的 MCP 设置里添加：

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

可用工具

生成工具通过任务队列运行，并立即返回任务 ID；下方每个工具的 返回值 字段描述的是任务成功后你从 getApiJob 获取的 result。请参阅生成调用的工作方式。

模型

精灵动画、动作迁移、精灵图集编辑和视频生成可选用 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	视频生成（默认）、根据参考生成视频（默认）	快速生成带配乐的电影感 480p 视频。1.5 点数/秒（根据参考生成时为 2.5 点数/秒），最短 5 秒
griffin-hd	视频编辑（默认）、视频生成、根据参考生成视频	与 Griffin 相同，但分辨率为 720p。2 点数/秒（根据参考生成时为 4 点数/秒），最短 5 秒。其输出文件过大，无法用于 upscaleVideo

旧版模型 — 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 Web 应用向用户展示的文档相同，因此偶尔会描述按钮而非参数；其中的实质内容同样适用于此处。要回答具体问题，请先使用 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 并列出有效值，因此猜错只会多花一次调用，而不会陷入死路。

服务器还会在初始化握手期间通过 instructions 字段向 MCP 客户端公布这两个文档工具，因此，使用能够显示服务器指令的客户端连接的模型会获知：生成内容前应先搜索文档。

积分： 免费

---

图像生成（createImage）

仅通过文本提示词生成精灵图、图标、背景、UI 资源和纹理（无需源图像）。要匹配现有图像的艺术风格，请使用 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	否	由客户端提供的 ID，用于稍后获取结果

积分： 每张图像 0.5

---

编辑图像（editImage）

使用文本指令修改现有图像（智能编辑）。

参数	必填	说明
image	是	要编辑的 URL 或 Base64 编码图像
prompt	是	更改内容的描述（例如，“移除背景”、“调暗一些”、“在天空中添加云朵”）
reference_image	否	用于提供风格或内容参考的 URL 或 Base64 参考图像
n	否	变化版本数量（1-4，默认值：1）
request_id	否	由客户端提供的 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	否	由客户端提供的 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	否	由客户端提供的 ID，用于稍后检索结果

返回：url、pose、motion_prompt

示例工作流：

1. 使用 generatePose 生成 Walk (Left) 姿势
2. 在 animateSprite 中直接使用返回的 motion_prompt，以获得最佳动画效果

**点数：**每张图像 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	否	由客户端提供的 ID，用于稍后检索结果

返回：url、camera_rotation、camera_elevation

**点数：**每张图像 0.5 点

---

移除背景（removeBackground）

移除单张图像的背景，返回主体独立呈现于透明背景上的图像。如需更广泛的编辑（不只是抠出主体），请改用 editImage。

参数	必填	描述
image	是	图像的 URL 或 base64 编码
crop	否	将结果裁剪至主体边界框（默认值：false）
creative_edit	否	生成更高质量的输出，但像素可能与输入不完全一致（默认值：true）。当主体必须与原图像素完全一致时设为 false，例如需要制作动画的现有精灵图
request_id	否	由客户端提供的 ID，用于稍后检索结果

**返回：**单个结果，包含 url（透明 PNG）

**点数：**每张图像 0.5 点

---

放大图像（upscaleImage）

将同一张图像提升至更高分辨率，最高可放大 4 倍，结果最长边不超过 2048px。源图像最长边必须小于 2048px；如果超过此尺寸，会在扣费前返回 HTTP 400 错误。

参数	必填	说明
image	是	URL 或 Base64 编码的图像，最长边小于 2048px
request_id	否	由客户端提供的 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 提供其他类型）。动画预设和 Directional Sprites 的 preset_id 可以重定向到该模型上，但并非适用于所有模型
joint_naming	否	与 rig 搭配使用：骨骼命名约定，与 rigModel 中相同（默认：smpl）
request_id	否	由客户端提供的 ID，可用于稍后获取结果

返回：model_url（GLB 文件）、不同角度的快照图像，以及 rigged

**积分：**使用 prop 时每个模型 4 积分，使用 hero 时 15 积分；rig 额外增加 1 积分，仅在模型返回时已完成骨骼绑定的情况下扣除 **处理时间：**使用 prop 时为 60-120 秒；hero 更慢

---

3D 模型图像（create3DModelImage）

生成可用于 create3DModel 的角色图像，这是在网页上使用 Directional Sprites 的第一步。create3DModel 会按原样转换传入的图像；此工具会先为它生成图像。可以传入提示词、自有图像，或两者兼传：传入的图像会被重新绘制为 3D 渲染图，提示词则用于说明要更改的内容。每次重新绘制都会生成一张新图像，因此可以再次调用以重试。

参数	必填	说明
prompt	二选一	不传入图像时：角色描述（例如“身穿绿色盔甲、全身像、站立的骑士”）。传入图像时：要进行的更改（例如“添加红色披风和一把剑”），可选。最多 1,000 个字符
image	二选一	自有图像的 URL 或 Base64 编码图像，将重新绘制为 3D 渲染图
request_id	否	由客户端提供的 ID，可用于稍后获取结果

**返回：**包含 url 的单个结果，可作为 create3DModel 的 image 参数传入

**积分：**每张图像 0.5 积分

---

3D 模型绑定骨骼（rigModel）

为现有 3D 模型生成骨架和蒙皮权重，使其能够制作动画。不会破坏几何体：此工具会返回一个新的已绑定骨骼的 GLB。使用 animate3DModel 之前，请先绑定模型。

参数	必填	描述
model	是	要绑定骨骼的 GLB URL 或 Base64 编码内容
rig_type	否	骨架样式预设：general（默认，适用于任何资产）、humanoid（动漫风格角色，骨架最密集）、game（经典游戏角色骨架），或带有命名关节的固定人形模板：humanoid_template（22 个关节）和 humanoid_template_hands（52 个关节，每只手有 5 根手指）。这些模板仅适用于双臂双腿的角色。动画预设（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）

为已绑定骨骼的 3D 模型生成文本驱动的骨骼动画（请先使用 rigModel 绑定骨骼）。动画质量不稳定，因此会返回多个候选动画供你选择。每个候选动画都是独立的、仅包含动画的 GLB（骨架 + 一个片段，不含网格），并附带一个 mp4 预览；选出最佳动画后，在游戏引擎或 three.js 中将其合并到模型上。

参数	必填	描述
model	是	要制作动画的已绑定骨骼 GLB URL 或 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）

将精选动画预设应用于已经绑定骨骼的 3D 模型（重定向动画）。与 animate3DModel 不同，动作来自专业精选的动画片段库，而非文本提示词，因此恰好只会返回 一个 片段。任何类型的骨架都可以使用预设（先用 rigModel 绑定模型，或使用 create3DModel 并设置 rig: true），但并非所有模型都能成功重定向动画；如果失败，任务会返回错误。listAnimationPresets 返回的任何预设 ID 均可使用。

参数	必填	描述
model	是	URL 或经过 base64 编码的已绑定骨骼 GLB（任意骨架类型）
preset_id	是	listAnimationPresets 中某个预设的 ID
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 秒

---

方向精灵

将 3D 模型渲染为带风格的精灵图，最多可从 8 个方向观看（摄像机围绕朝南的角色布置）。一次调用中请求的所有方向都会一起渲染，并使用相同的画面尺寸、比例和地面，因此精灵图能够对齐。常见流程：

1. （可选） 角色图像：通过提示词使用 create3DModelImage 生成，或使用你自己的图像重新绘制为 3D 渲染图。
2. 已绑定骨骼的模型：使用该图像和 rig: true 调用 create3DModel（或者对已有模型使用 rigModel）。任何类型的骨架都可以使用动画预设，但并非所有模型都能成功重定向动画。
3. （可选） 最多一个动画：使用 listAnimationPresets 中的 preset_id，或使用 animate3DModelPreset 或 animate3DModel 为此模型生成的 animation_url。如果不提供动画，精灵图将显示静止姿势。
4. listDirectionalSpriteStyles：选择外观。
5. previewDirectionalSprites：免费预览。
6. 动画精灵图集使用 createDirectionalSprites，静态图像使用 createDirectionalStills。

listDirectionalSpriteStyles

免费。返回 styles（每个样式包含 id、label、description、family、pixel、thumbnail_url、version 及其 settings / advanced_settings：包含 name、类型为 choice、bool 或 color 的 kind、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 或经过 base64 编码的 GLB（带骨骼，用于为其添加动画）
animation_url	否	为此模型制作的动画：来自 animate3DModel 或 animate3DModelPreset 的 glb_url（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	否	由客户端提供的 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（仅在 margin_ratio_mode 为 manual 时使用）。适用于向侧面延伸的动画，例如挥剑或出拳
margin_ratio_vertical	否	精灵周围的垂直留白，比例为 0.0–1.0（仅在 margin_ratio_mode 为 manual 时使用）。适用于向上或向下延伸的动画，例如跳跃
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	否	由客户端提供的 ID，用于稍后获取结果

返回值： spritesheet_url（精灵图表）、video_url（动画的 mp4 - 将其作为 video 传给 transferMotion，或作为 spritesheet_video_url 传给 createSpriteAudio）、audio_url（仅 hydra 和 hydra-plus：生成音效（mp3）的 URL，因此无需调用 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 每秒 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——这些模型支持中间关键帧。此处的动作提示词为可选项：省略时，动作将完全根据关键帧生成。如果只需要起始帧和结束帧，使用带有 final_image 的 animateSprite 即可实现相同效果。

参数	必填	描述
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（仅在 margin_ratio_mode 为 manual 时使用）
margin_ratio_vertical	否	精灵周围的垂直留白比例，取值为 0.0–1.0（仅在 margin_ratio_mode 为 manual 时使用）
margin_ratio	否	已弃用——两个轴使用相同的留白；不可与按轴设置的参数同时使用（否则会返回 400 错误）
margin_ratio_mode	否	auto（默认）、manual、none
augment_prompt	否	在后台扩充动作提示词（默认：true）
duration	否	默认 3 秒。Hydra / Hydra+：3–5 秒；Forge / Forge Pixel：按 0.5 秒递增，范围为 1–5 秒。三个关键帧需要足够时长：1 秒时，开场过渡会被压缩掉
gif	否	生成动画 GIF（默认：false）
individual_frames	否	提取单独的帧图像（默认：false）
spritesheet_with_background	否	同时返回保留背景的精灵表，即移除背景之前的版本（默认：false）
request_id	否	由客户端提供的 ID，供稍后检索结果

**返回：**与 animateSprite 的结构相同（spritesheet_url、video_url、hydra 和 hydra-plus 上的 audio_url、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
• perspectives：包含 id、name、description 的数组（所有动画均支持所有视角）
• directions：["N", "NE", "E", "SE", "S", "SW", "W", "NW"]（所有动画均支持所有方向）

**积分：**免费

---

动作迁移（transferMotion）

将视频或动画预设中的动作迁移到静态精灵图上，生成动画精灵图表。需要精确复制动作时使用此工具——可以使用 listAnimationPresets 中的标准行走或攻击循环，也可以使用自己的片段；若要用文字描述动作，请改用 animateSprite。

参数	必填	描述
image	是	精灵图的 URL 或 Base64 编码图像
video	否	用作动作来源的视频 URL：可以是 animateSprite 返回的精灵图表中的 video_url，也可以是自己的片段。效果最好的是时长不超过 4 秒的视频。必须提供 video，或同时提供 preset_id、perspective 和 direction；如果两者都提供，则使用视频
preset_id	否	要使用的动画预设 ID，用来代替视频 URL，来源为 listAnimationPresets。使用预设时，必须提供 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 秒，否则为模型支持的最短时长，因此 hydra（默认模型）为 3 秒。Hydra：3–5 秒，以 0.5 秒为步进；Forge / Forge Pixel：1–5 秒。较长的参考片段或预设会被压缩以适配，因此请传入预设自身的 duration 以保留其节奏
request_id	否	由客户端提供的 ID，用于之后获取结果

**返回值：**与 animateSprite 返回的结构相同（spritesheet_url、video_url、hydra 上的 audio_url、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 精灵表（改进）。传入你从 animateSprite、animateSpriteKeyframes、transferMotion 或先前的编辑中收到的 spritesheet_url；它必须是你在过去 7 天内生成的精灵表（不接受外部 URL）。省略 duration、frames、frame_size、crop 和 model，以保留源精灵表的对应值。

参数	必填	描述
spritesheet_url	是	你在过去 7 天内生成的精灵表 URL
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	否	由客户端提供、用于稍后获取结果的 ID

**返回：**与 animateSprite 返回相同结构（spritesheet_url、video_url、gif_url、num_frames、num_cols、num_rows 等）。仅在对 hydra 使用 prompt 模式编辑时会生成新音频；如果源精灵表有 audio_url，则 fix_loop、outpaint 和 improve 会保留该值

积分：fix_loop、outpaint 和 improve：每秒输出时长固定消耗 1 积分；计费时长以源精灵表的视频时长为上限，无最低消费，且忽略模型（3 秒的精灵表消耗 3 积分，无论传入的 duration 为何）。prompt 模式编辑：按模型计费——Hydra 每秒 3 积分（3 秒 = 9 积分），Forge / Forge Pixel 每秒 2 积分，无最低消费（3 秒 = 6 积分）

---

Sprite 表音效（createSpriteAudio）

为你之前生成的 Sprite 表动画生成音效。使用 hydra 制作的 Sprite 表已自带 audio_url，因此请对 forge / forge-pixel 的输出调用此工具，或用于替换 hydra 的音效。

参数	必填	描述
spritesheet_video_url	是	你从 animateSprite、animateSpriteKeyframes、transferMotion 或 editSpritesheet 收到的 video_url；必须属于你在过去 7 天内生成的 Sprite 表
prompt	否	音效描述，例如“金属剑挥动并伴有呼啸声”
request_id	否	由客户端提供、用于再次查找任务的 ID；不得使用你已用于其他生成任务的 ID

**返回：**生成的音频文件的 url。音频也会附加到 Sprite 表上，因此会作为该条目在 listGenerations 中的 audio_url 显示。

**积分：**每次调用 3 积分

---

视频生成（createVideo）

根据源图像和动作提示词生成短视频（图生视频）。必须提供源 image：若要仅凭文本生成视频，请先调用 createImage 并为其制作动画，或使用 createVideoFromReferences。当前的两种模型都会生成配乐，因此无需单独生成音频。

参数	必填	描述
image	是	起始帧的 URL 或 base64
prompt	是	动作描述（例如：“镜头推近”“角色向前行走”）
duration	否	默认值为 5 秒。Griffin / Griffin HD：5–15 秒，以 1 秒为步进
model	否	griffin（默认；480p，带配乐）、griffin-hd（720p，带配乐；之后无法放大）。旧版，新项目请避免使用：blitz、eagle、eagle-audio（别名 standard→blitz）
final_image	否	用于插值的结束帧
request_id	否	由客户端提供、用于稍后检索结果的 ID

返回：url、duration、has_audio

**积分：**费率 × 秒数 - Griffin：每秒 1.5 积分（默认 5 秒 = 7.5）；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（默认；480p，带配乐）、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	否	由客户端提供、用于稍后检索结果的 ID

返回：url、duration、has_audio

**积分：**费率 × 秒数；相同模型下费用高于 createVideo - Griffin：每秒 2.5 积分（默认 5 秒 = 12.5）；Griffin HD：每秒 4 积分（5 秒 = 20）。旧版：Eagle 每秒 1.5 积分，Eagle with Audio 每秒 2 积分。

---

编辑视频（editVideo）

通过文本提示词和可选的参考图像编辑之前生成的视频（视频转视频）。传入从 createVideo、createVideoFromReferences 或先前的编辑中收到的 url；视频必须是你在过去 7 天内生成的（不接受外部 URL）。

参数	必填	说明
video	是	你在过去 7 天内生成的视频 URL
prompt	是	描述所需更改的编辑指令
images	否	最多 5 张用于引导编辑的参考图像（URL 或 base64）
duration	否	输出时长，单位为秒：5–15。省略则保留源视频的时长
model	否	griffin-hd（默认；720p，带音轨）。旧版，新项目请避免使用：eagle
request_id	否	由客户端提供的 ID，用于稍后获取结果

返回： url、duration、has_audio

积分： Griffin HD：每秒 2 积分（5 秒 = 10）

---

升级视频分辨率（upscaleVideo）

将之前生成的视频升级到两倍分辨率（2x）。传入从 createVideo、createVideoFromReferences 或 editVideo 收到的 url；视频必须是你在过去 7 天内生成的（不接受外部 URL）。源视频的两个尺寸都必须小于 960 像素：griffin（480p）输出符合要求，griffin-hd（720p）输出则不符合（横向或纵向均如此），因此如果打算升级分辨率，请使用 griffin 生成。源视频尺寸过大时，任务会失败，预扣积分将退还。

参数	必填	说明
video	是	你在过去 7 天内生成的视频 URL，两个尺寸都小于 960 像素
request_id	否	由客户端提供的 ID，用于稍后获取结果

返回： url（宽度和高度均为 2 倍，时长不变）、duration、has_audio

积分： 按时长统一收费，与模型无关：每秒 0.2 积分（5 秒 = 1）

---

音效生成（createSoundEffect）

根据文本描述生成游戏音效。

参数	必填	说明
description	是	音效描述（例如：“激光枪开火”“在碎石路上行走的脚步声”“拾取硬币”）
duration	否	0–10 秒（0 = 自动）
request_id	否	由客户端提供的 ID，用于稍后获取结果

积分： 每个音效 2 积分

---

氛围音生成（createAmbiance）

根据文本描述生成环境音景和背景氛围。

参数	必填	说明
description	是	氛围描述（例如：“黄昏时分的多风森林”“繁忙的中世纪集市”“飞船引擎的嗡鸣声”）
duration	否	时长，单位为秒（0 = 根据描述自动确定）
loop	否	生成可无缝循环播放的氛围音（默认：true）
augment_prompt	否	在后台扩展提示词（默认：true）
request_id	否	由客户端提供的 ID，用于稍后获取结果

积分： 每次生成 2 积分

---

音乐生成（createMusic）

生成背景音乐和主题音乐。

参数	必填	说明
description	是	音乐描述（例如：“史诗般的管弦乐战斗主题曲”“舒缓的钢琴旋律”“8 位芯片音乐”）
lyrics	否	人声曲目可选的歌词
request_id	否	由客户端提供的 ID，用于稍后获取结果

积分： 每首曲目 3 积分

---

音频转换（createAudioTransform）

使用文本提示词重新混音或转换现有音频样本。

参数	必填	描述
sample	是	要重新混音的源音频样本 URL 或 Base64 编码内容（最大 15MB）
prompt	是	引导重新混音的描述（例如，“让它听起来像 80 年代的合成器浪潮曲目”）
duration	否	时长（秒）：0（自动，与源音频匹配）或 10–180，以 10 为步长
modification_strength	否	对源音频的修改强度，范围为 0–1（默认值：0.6；0 = 接近原音）
augment_prompt	否	在后台增强提示词（默认值：true）
request_id	否	由客户端提供的 ID，用于稍后获取结果

**积分：**每次生成 3 积分

---

语音生成（createVoice）

生成独特的角色语音。

参数	必填	描述
voice_description	是	角色描述（例如，“粗哑的老战士”“活泼的小女孩”）
text	是	要朗读的文本（最多 200 个字符）
type	否	human（默认值）或 non-human
request_id	否	由客户端提供的 ID，用于稍后获取结果

**积分：**每个语音 1 积分

---

文本转语音（createSpeech）

根据音频样本克隆语音。

参数	必填	描述
text	是	要朗读的文本（最多 1000 个字符）
sample	是	用于语音克隆的 URL 或 Base64 音频样本
request_id	否	由客户端提供的 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	否	由客户端提供的 ID，用于稍后获取结果

**积分：**每次生成 1 积分

---

检查任务（getApiJob）

轮询由任意工具启动的生成任务状态。每个任务都会返回 {id, status}；使用该 ID 调用 getApiJob，直到 status 为 succeeded（然后读取 result，其结构与工具文档中说明的输出完全一致）或 failed（然后读取 error）。

参数	必填	描述
id	是	生成工具返回的任务 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 启动的生成任务。不包括 Web 应用中的任务。

参数	必填	描述
status	否	要包含的逗号分隔状态（queued、running、succeeded、failed、canceled）。默认包含全部状态
limit	否	要返回的任务数量上限（默认值：50，最高为 100）

**返回：**包含 id、status 和时间戳的任务对象数组

**积分：**免费

---

取消任务（cancelApiJob）

取消仍在队列中的任务，并退还其消耗的点数。已开始运行的任务无法取消（调用会返回 409）。

参数	必填	描述
id	是	要取消的任务 ID

返回： 已取消的任务

点数： 免费，并退还该排队任务消耗的点数

---

生成历史记录（listGenerations）

查看 API 和 Ludo 网页工作室中的生成历史记录，并支持筛选、文本搜索和分页。此工具取代了按类型获取结果的工具（getImageResults、getSpriteResults、getVideoResults、getAudioResults、get3DModelResults），这些工具已从 MCP 中移除，并在 REST API 中弃用。

参数	必填	描述
type	是	image、spritesheet、video、audio、3d
source	否	api（最近 7 天内通过 API/MCP 生成的内容）、web（通过网页工作室生成的内容，不限时间）或 all（默认值）
search	否	自由文本搜索。每个以空格分隔的词都必须匹配条目的标签或其中一个文本字段（提示词、提示、风格、标签等），因此“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 错误。请改用不同的提示词、模型或设置重试。描述你尝试做什么，以及出了什么问题。每个问题提交一份报告，不要包含个人数据、机密信息或文件内容；如果你是 Agent，请告知用户你提交了什么。

参数	必填	描述
category	是	bug、limitation、feature_request、praise 或 other。生成内容看起来不对属于模型限制，而非错误：请勿报告
message	是	你尝试做什么、发生了什么，以及什么会有所帮助（最多 4,000 个字符）
operation	否	反馈涉及的工具，例如 animateSprite
job_id	否	反馈涉及的任务 ID（如有）
agent	否	提交反馈的 Agent 或应用，例如 Claude Code

返回值：ok 和报告的 id

**积分：**免费

---

生成调用的工作方式

每次生成都会进入任务队列，通过 MCP 调用的所有生成工具都是异步的。生成调用会立即返回 {id, status: "queued"}，而不会阻塞，因此 GPU 运行时不会有请求一直保持打开状态，也不会有 MCP 传输在生成过程中超时。之后，你可以使用 getApiJob 获取结果。MCP 工具没有 async 参数：你无需设置此选项。

（如果直接调用 REST API，而非通过 MCP 调用，工作方式也相同：请求默认是异步的，并返回带有任务 ID 的 202。同步响应已弃用，但在请求负载中传入 async: false 仍会启用同步响应，并将一直受支持。）

获取结果

# 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(费率 × 实际生成秒数, 模型最低费用)，且不会超过你请求的时长对应的费用；任务完成时会退还差额。如果任务失败，或你在任务仍在队列中时取消任务，所有积分都会退还。每个工具上方的 积分 行都会说明费率和最低费用；服务端也会在其 instructions 字段中说明这项规则。

公平使用限制

• 每个账户最多可有 50 个任务处于排队或运行状态。 超出此数量的提交会返回带有代码 PENDING_JOBS_LIMIT 的 429；请等待任务完成后再提交。
• 每个 API 密钥在 5 分钟内最多可对读取端点发起 150 次请求（任务状态、任务列表、生成历史记录、账户、功能文档）。429 响应会包含 Retry-After。
• 每个 API 密钥在 5 分钟内最多可对文档搜索（searchDocs）发起 60 次请求，每天最多 1,000 次。

稍后查找结果

每个生成工具也都接受可选的 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、source（api、web 或 all）、自由文本 search 或日期筛选，并分页浏览结果。通过 API 生成的结果可保留 7 天。

---

资产 URL 过期时间

所有生成的资产 URL（图像、精灵图集、视频、音频、3D 模型）都指向 Google Cloud Storage 链接，这些链接会在 7 天后过期。任何需要保留超过此期限的资产，尤其是用于生产环境的资产，都必须立即下载并保存在本地（或重新上传到永久存储）。切勿将返回的 URL 保存为永久引用。

服务器还会在初始化握手期间通过其 instructions 字段向 MCP 客户端告知此事，因此，通过会显示服务器说明的客户端连接的模型会自动收到提醒。

---

示例提示词

创建游戏资产

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.ludo.ai/api-documentation

支持

• 文档
• Ludo AI 网站
• GitHub 问题

许可证

专有软件 - 服务条款请参阅 ludo.ai/terms。