mint-api

Mint API

将 Mint 的生产 API 用作账户拥有的资产流水线。

安全开始

1. 阅读 references/quickstart.md。
2. 如果需要快速了解当前公开文档的概览，请获取 https://docs.mint.gg/llms.txt。只有在任务需要了解多个指南的更多背景时，才获取 https://docs.mint.gg/llms-full.txt。
3. 使用不熟悉的端点或字段前，请阅读生产环境的 OpenAPI 契约：https://api.mint.gg/openapi.json。这是端点和架构的准确信息来源。
4. 从环境中读取 MINT_API_KEY。切勿打印、粘贴、传输给无关服务或提交此密钥。
5. 仅在用户授权进行实时身份和 Credits 检查时，运行 node scripts/check-connection.mjs。

工作流

1. 选择服务和 fast/standard/production 预设。省略 generationMode 以使用推荐的 auto 工作流；只有集成需要做出 Preview 决策时，才选择 review。
2. 启动生成。只有当用户希望在 Mint 中显示特定标题时，才使用 name。
3. 保存返回的操作 ID。当操作创建资产时，从 operation.resource 中读取其类型和 ID。
4. 使用有界指数退避轮询操作。可使用 scripts/poll-operation.mjs 或等效的应用逻辑。
5. 在 review 模式下，停在 preview_ready 状态；仅根据用户的意愿批准或修改。
6. 处理所有终态，包括 partially_succeeded。
7. 获取资产，并通过清单查找其文件，不要猜测文件 URL。

有关服务工作流和审核操作，请阅读 references/service-workflows.md；有关资产交付，请阅读 references/assets-and-files.md。

不变量

• 通过 API 创建的资源属于 Mint 账户，并可通过 API、MCP 和 Mint 使用。
• World、3D Model 和 Asset Pack 生成接受一个 imageUrl 或 2–8 个 sourceImages，但不能同时提供两者。Materials 和 Material Packs 仅接受一个 imageUrl。
• 使用自然语言 prompt 启动 Asset Packs；Mint 会规划各个资产及其统一风格。只有需要精确控制时，才使用可选的 itemCount、assetPackType 或 styleGuide。如果未提供数量，也未在提示词中说明数量，Mint 将创建 8 个资产。如果没有适合的专用类型，Mint 将使用 general_asset_pack。
• 仅对 3D Models 和 Asset Packs 使用 riggingPose: "t_pose" | "a_pose"。它会准备一个全身、正面、空手的类人生物 Preview，以便后续绑定；它不会为资产绑定骨骼或制作动画。
• 使用 POST /v1/models/{modelId}:convert 转换账户拥有的 3D Model。请求体中只发送所需格式和可选名称；切勿发送外部源 URL。
• Provider 模型 ID 不属于公开契约。请发送公开预设。
• 将 totalReserved、monthlyReserved 和 topUpReserved 视为待处理的 Credits，而非已结算支出。
• 当操作报告 billing_required 时，显示其账单操作并保留操作 ID。账单问题解决后，如果操作已有 Preview 或中间资源，则继续该操作；如果未创建资源，则使用相同的 Idempotency-Key 重试原始请求。
• 限制轮询、重试、批次大小和总成本。遵循 Retry-After。Mint 每分钟允许 600 次经过身份验证的请求，以及每个账户每分钟 30 次付费任务启动；这些限额由账户的所有 API 密钥共享。
• 对常规变更操作省略 Idempotency-Key。如果集成会重试结果不确定的变更操作，请在首次尝试前生成一个稳定的密钥，并仅在重试该请求时重复使用。
• 切勿暴露内部 URL、本地测试密钥、Provider 凭据、私有文档或仅用于实现的模型 ID。
• 不要将 API 密钥放在浏览器或移动客户端中。请从可信的服务器端代码调用 Mint。

设计错误处理前，请阅读 references/errors-and-retries.md。