游戏素材生成与编辑 REST API 文档

通过谷灵AI REST API 创建角色、动画、场景与声音素材，了解 API Key 鉴权、生成参数、任务查询、下载权限、积分预算及失败处理。

接入方式

使用 API Key，在请求头传入 Authorization: Bearer YOUR_API_KEY。这里展示供外部工具使用的素材接口。

服务地址 https://www.gulingai.com/，请求时拼接下方接口路径。生成是否开放以模型查询结果为准，角色配音与游戏音效配置开通后可用。

公开接口

生成请求示例

{
  "max_credits": 5,
  "idempotency_key": "example-generation-001",
  "request": {
    "kind": "background",
    "prompt": "森林中的小镇，晨光透过树叶",
    "style": "手绘水彩",
    "width": 1024,
    "height": 1024,
    "params": {
      "transparent": false
    }
  }
}

将上述 JSON 作为 POST /v1/generations 请求体，无需先获取报价。图片固定 5 积分/次，精灵动作或动画特效固定 30 积分/次；角色配音固定 15 积分/次，使用音频生成模型，配置开通后可用。编辑图片在 request 中增加本人素材的 source_asset_id，并提交到 /v1/generations/edit。原报价接口保留兼容，quote_id 为可选字段。

类型与交付

类型支持 character、animation、background、element、button、tileset、building、vfx、voice、sound。动作需传入角色图片和 action，可选 idle/walk/run/attack/hurt/death，每次处理一个动作。按钮交付四个色彩状态；特效可选择动画或静态；动画特效通过视频模型交付帧序列和图集。request.params.output_duration 可指定 1–4 秒导出长度（支持小数），省略时自动提取动作或循环周期。ZIP 附带素材配置与校验信息。

角色方向

character 的 params.direction_count 支持 1（默认）、4、8；单方向参考图选填，四/八方向必须在 reference_asset_ids 选择一张参考图，不能使用图集。单方向通过 params.direction 选择 south/southwest/west/northwest/north/northeast/east/southeast（默认 east），多方向不传 direction。params.view 支持 side/top_down/isometric（默认 side）。多方向须使用透明背景，每张方向图 5 积分，完整四/八方向分别为 20/40 积分。交付独立方向 PNG、合并图集、含方向名称和切片坐标的 manifest.json 及 ZIP；参考图、合并图集和打包不另收费。全部交付后扣费，失败或取消释放整笔预留积分。

角色配音

voice 请求只需 kind、prompt（角色台词，最多 100 字）和 params，不需要画布或美术风格。params.voice_style 为声音描述（最多 500 字），language 为 zh-CN、en-US 或 ja-JP，speech_rate 为 0.5–2（默认 1），format 为 wav 或 mp3（默认 wav）。单次原始音频最长 120 秒，长台词建议分段。完成后支持在线播放、下载音频与素材包。

游戏音效

sound 请求只需 kind、prompt（音效描述）和 params。params.sound_duration 为目标时长 0.5–30 秒（默认 3），loop 为循环要求（默认 false），format 为 wav 或 mp3（默认 wav）。与配音共用音频生成模型；按目标时长计费，5 秒以内 10 积分，超出部分每秒增加 1 积分，不足 1 秒按 1 秒计算（5.5 秒为 11 积分，6.5 秒为 12 积分）。完成后可试听、循环播放和下载，实际时长与首尾衔接以交付音频为准。

动画修复、地图与平铺

角色动画每次仅调用一次视频生成，随后跟踪像素根点、对齐并生成质量报告。不满意时可自行重新生成，每次成功交付单独扣费。get_generation 的 result 包含 quality、alignment、candidates 和异常帧索引；工作台可逐帧播放和显示根点。POST /v1/generations/repair 或 MCP repair_animation_frame 传 generation_id、frame_index（从 0 开始）、instruction、max_credits（至少 5）与 idempotency_key，修复一帧后生成新的完整素材包，原版本保留。

地图块 params.tile_size 为 16/32/64/128，最多 1024 块；ZIP 附带 tileset.json（索引、切片坐标、视觉邻接规则）及拼接接缝预览。背景 params.tileable 可为 none/horizontal/vertical/both；输出四宫格平铺预览和 tiling.json 边缘检测报告。两类素材 params.seam_threshold 可设 0.001–0.3，默认 0.08。未通过的接缝会明确标记，可继续编辑原图。视觉邻接不替代地形语义与碰撞配置。

素材有效期与分页

素材生成或上传后有效期为 30 天，过期后不再提供预览、下载、编辑或参考使用；生成与计费记录保留，请及时下载保存。素材信息包含 expires_at（UTC 时间）。

GET /v1/generations 无参数时返回最近 50 条任务数组。传入 limit（1–50）、cursor、available_only、image_only 或 kind 时，返回 items 和 next_cursor；下一页使用返回的 next_cursor。MCP list_generations 支持相同参数。

响应与扣费

成功响应为 { data: ... }；错误为 { error: { code, message } }。生成提交返回 202，轮询任务直至完成。图片、视频、音频和 ZIP 下载需要同一账户的 Key 并具备 assets:read 权限。

400 参数错误；401 鉴权失败；402 积分不足；403 权限不足；409 报价、幂等或预算冲突；429 频率限制；503 服务未配置或暂不可用。成功交付扣费，失败释放；相同任务查询和幂等重试不重复扣费。

{
  "project_id": "prj_替换为本人项目ID",
  "name": "骑士基础动作",
  "items": [
    {
      "key": "hero",
      "request": {
        "kind": "character",
        "prompt": "穿红色披风的骑士，单个全身角色",
        "params": {
          "direction_count": 1,
          "direction": "east",
          "view": "side"
        }
      }
    },
    {
      "key": "idle",
      "source_item_key": "hero",
      "source_direction": "east",
      "request": {
        "kind": "animation",
        "prompt": "原地待机，平稳呼吸",
        "params": {
          "action": "idle",
          "fps": 12,
          "loop": true,
          "output_duration": 2
        }
      }
    }
  ]
}