DEVELOPER GUIDE

AI 游戏素材制作与下载入门指南

了解谷灵AI 游戏素材制作流程：选择类型、设置风格与画布、上传参考图、生成或编辑、检查结果并下载素材，附积分规则和当前功能说明。

开始制作

注册、验证邮箱并登录。
选择角色、动作、背景、元素或按钮工作台，填写描述、风格与画布。
上传参考图；编辑时选择自己的原图，动作制作时选择角色图片。
查看本次积分费用并直接提交，在素材与任务页查看结果并下载。

图片生成/编辑 5 积分/张；角色单方向 5 积分、四方向 20 积分、八方向 40 积分，精灵动作或动画特效固定 30 积分/次，角色配音固定 15 积分/次；游戏音效按目标时长计费，5 秒以内 10 积分，超出部分每秒增加 1 积分，不足 1 秒按 1 秒计算，成功交付后扣费，失败或取消释放预留积分。动作按单次动作或循环周期导出，包含帧序列和精灵图集；也可指定 1–4 秒导出长度。消费明细可在个人中心的积分流水中查看。草稿仍可保存在当前浏览器。

功能状态

网站生成与编辑入口、任务记录、素材权限、积分预留结算、MCP 工具已实现。接入真实模型后需验证生成质量与成本；角色配音与游戏音效已接入音频生成模型，配置开通后可用；背景音乐与内部音频审核列表将在后续开发。

动作导出包含帧序列、图集、根点与对齐数据、候选评分，工作台支持逐帧修复。地图块附带索引、视觉邻接规则及接缝预览；背景支持指定方向平铺验证。自动检查后仍可预览确认复杂形体与动作效果。支付服务尚未开通。

选择素材类型 ↗

项目素材生产与引擎导出

在素材项目与套装固定引擎版本、风格、色板、画布、枢轴点及纹理预算。网站、REST、MCP 使用同一套规范、任务、版本和积分记录。

调用 set_project_profile 创建规范；更新时传 project_id 与 expected_version，旧版本保留。
调用 plan_asset_bundle 创建免费计划，保存规范快照；动作可以通过 source_item_key 依赖前序角色，多方向须指定 source_direction。
核对 total / planned 费用，调用 submit_asset_bundle，传入 max_credits 和幂等键。系统逐项预留和结算，不预留整套费用、不自动付费重试。
用 get_bundle_report 查询；失败和暂停不会被查询触发重做。暂停后使用原预算和幂等键显式提交可继续；Key 失效后需用有权限的 Key 重新授权。
预览并用 review_bundle_item 记录人工验收。需要修改时调用原生成、编辑或单帧修复工具，再 select_bundle_item 替换指定项，旧版本保留。
调用 export_engine_bundle 导出当前或指定 revision。默认要求全部项通过技术检查且人工接受；项目测试可显式传 allow_unreviewed: true。

项目权限为 projects:read/write，套装权限为 bundles:read/write。执行套装还需 generations:write，替换需 generations:read，导出需 assets:read。已有 Key 不会自动增加权限，请创建包含所需权限的新 Key。

工具	用途	需要权限
`set_project_profile`	创建项目或追加不可变美术规范版本；更新必须传 expected_version。不会生成或扣费。	projects:write
`list_projects`	列出本人素材项目，最多 50 项，支持游标。	projects:read
`get_project_profile`	读取本人项目及指定的不可变规范版本；省略 version 使用当前版本。	projects:read
`plan_asset_bundle`	免费创建不可变套装计划，最多 64 项。可用 source_item_key 依赖前序角色；多方向角色依赖须指定 source_direction。不会生成或冻结积分。	bundles:write
`list_asset_bundles`	列出本人套装摘要，支持项目筛选和游标；不会推进任务或扣费。	bundles:read
`submit_asset_bundle`	授权执行已规划套装。总费用不得超过 max_credits；逐项冻结和结算，不预留整套费用。仅执行一次，不自动付费重试；重启可恢复，Key 失效停止新任务。	bundles:write、generations:write
`get_bundle_report`	只读套装进度、费用、技术问题、人工验收和源版本；revision 可查看历史快照，不会触发生成。	bundles:read
`cancel_asset_bundle`	停止未提交项并取消未完成子任务，释放相应预留积分；已交付素材与扣费保留。	bundles:write、generations:write
`select_bundle_item`	用本人已完成且规格匹配的任务替换一个套装项，创建新修订并清除该项验收；不调用模型、不扣费。	bundles:write、generations:read
`review_bundle_item`	记录当前所选素材的人工验收（accepted/rejected/pending），创建套装修订。技术检测与美术验收分别记录。	bundles:write
`set_bundle_item_metadata`	设置动作事件、挂点及碰撞框并创建新修订。时间以秒计，坐标归一化且原点在画布左上角；这些数据由开发者定义，不从图片自动推断。修改后重新验收该项。	bundles:write
`export_engine_bundle`	免费导出指定修订的带扩边分页图集、清单、质量报告和 Unity/Cocos 接入源码；默认要求全部项人工接受且技术检查通过。allow_unreviewed=true 显式导出测试包；引擎源码仍须在目标版本编译实测。	bundles:read、assets:read

套装计划示例

{
  "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
        }
      }
    }
  ]
}

将示例作为 plan_asset_bundle 参数，或 POST /v1/bundles/plan。project_id 替换为本人项目，规范画布须为不超过 512 的正方形。示例生成一个角色和一个待机动作，共 35 积分；计划本身不生成、不扣费。

局部修复与配置

upload_reference 可上传同尺寸 PNG 蒙版：白色为修改区、黑色为保护区，灰度乘透明度决定混合权重。静态原图编辑传 request.edit_mask_asset_id；repair_animation_frame 传 mask_asset_id。蒙版外保留原 RGBA 像素，蒙版修复动画时保留其他帧和画布，不重新对齐整套帧。工作台也支持画笔绘制修改区域。

set_bundle_item_metadata 设置秒制动作事件、挂点和碰撞框；坐标归一化，原点在画布左上角。这些信息由开发者定义，不根据图片自动推断。验收、替换和配置修改须传 expected_revision，版本冲突时先重新读取。

REST 对应接口

`POST /v1/projects`	set_project_profile
`GET /v1/projects`	list_projects
`GET /v1/projects/:project_id`	get_project_profile
`POST /v1/bundles/plan`	plan_asset_bundle
`GET /v1/bundles`	list_asset_bundles
`POST /v1/bundles/:bundle_id/submit`	submit_asset_bundle
`GET /v1/bundles/:bundle_id`	get_bundle_report
`POST /v1/bundles/:bundle_id/cancel`	cancel_asset_bundle
`POST /v1/bundles/:bundle_id/select`	select_bundle_item
`POST /v1/bundles/:bundle_id/review`	review_bundle_item
`POST /v1/bundles/:bundle_id/metadata`	set_bundle_item_metadata
`POST /v1/bundles/:bundle_id/export`	export_engine_bundle

MCP 导出响应的 download.download_url 可直接供 Agent 下载 ZIP；create_asset_download 可为其他素材创建 5 分钟下载链接，无需读取长效 Key。Key 吊销后链接也失效。

交付与验证边界

ZIP 包含分页扩边图集、稳定帧标识、bundle.json、原交付配置、质量报告、SHA-256 校验清单和所选引擎的接入源码。矩形原点在左上角，pivot 在左下角，无旋转、无透明裁切。Unity 适配器需要 2D Sprite 包；Cocos 适配器提供 Sprite 播放组件。安装步骤见 ZIP 内 README.txt，资源更新时保留引擎生成的 .meta 文件。

技术检查不证明角色身份、动作语义、美术效果和实机性能合格。固定色板会处理可见像素颜色；提示词中的美术要求仍需人工检查。全部资源仍受 30 天有效期约束。下载后请归档，并在目标引擎和手机上完成编译、画面、资源更新与性能测试。