Api: 积分与用量

Direct API 调用如何扣费、结算和退款，如何先为作业报价，以及如何读取密钥的消费和账目。

Direct API 从你组织的余额中扣除 Morphic 积分，与 Studio 使用的是同一个积分池，并且每个响应都会说明扣除了多少。

Direct API 调用按你组织的 API 费率计费，这可能与同样的工作在 Studio 中的费用不同。API 给你的每个数字都已按此费率计算：plan_media 报价、estimated_credits、billing 块、生成任务读取、webhook 和 /usage。
费率按组织设置，不公开发布。你的客户联系人可以提供你的 API 费率表。
费率变更适用于变更之后启动的生成任务；正在运行的生成任务按其启动时的费率结算。
在 Studio 的“设置 > 积分”中，API 消费会以单独的一行“API”显示在成员旁边，“按密钥拆分 API”会按密钥细分。它从组织的积分中扣除，但从不占用成员的分配额度，并受每个密钥的积分上限约束。

生成任务如何扣费

启动时，按报价扣除生成任务的费用。启动响应会在 billing.credits_charged 和 result.estimated_credits 中报告该金额。
有些输出按实际产出计价：语音和音乐按产出时长，时间线渲染按计算时间。它们带有 credits_settle_on_output_duration: true；启动时的扣费是最低金额，最终金额在生成任务结束时结算。
以 failed 或 cancelled 结束的生成任务会全额退款，billing.credits_refunded 会报告退还的积分。成功的生成任务也可能带有部分退款，例如结算的输出比启动扣费所覆盖的时长更短时。
生成任务进入最终状态后，billing.credits_charged 就是账目上的净总额（启动扣费，加上或减去结算差额，再减去 credits_refunded），且 credits_are_final 为 true。失败或取消的生成任务最终为 credits_charged: 0，credits_refunded 等于其被扣除的金额。

字段	含义
`estimated_credits`	启动时报价并扣除的金额
`credits_charged`	到目前为止为此生成任务记录的净积分，已计入结算和退款
`credits_refunded`	为此生成任务退还的所有积分：`failed` 或 `cancelled` 时为全部扣费，成功时为任何部分退款；没有退款时为 `0`，永远不为负数
`credits_are_final`	在生成任务运行期间，或仍有结算或退款待处理时为 `false`；不会再有任何变化时为 `true`
`credits_settle_on_output_duration`	当启动扣费是根据产出输出结算的最低金额时为 `true`

生成任务运行期间，credits_charged 等于启动扣费。生成任务进入最终状态后再次读取，即可获得结算后的金额；webhook 只会在那之后发送。

每个响应中的计费信息

调用响应中的 billing 块报告的是调用返回时扣除的积分；调用工具按调用类型列出了它。退款在之后发生，因此会显示在生成任务上（GET /generations/{id} 和 /usage），而不会出现在原始响应中。

在调用内返回结果、但工作失败的付费工具（例如 analyze_video），会返回 credits_charged: 0，并将 credits_refunded 设为退款金额。
Morphic-Credits-Charged: <integer> 响应头携带的数字与 billing.credits_charged 相同，但幂等重放除外：重放不会再扣除任何积分，响应头为 0，而其响应体会重复原始扣费金额。

先报价再消费

POST /v1/direct/tools/plan_media 会校验最多 20 个步骤的计划，并为其能够报价的步骤报价，不会启动任何任务，也不会扣除任何积分。

curl -s https://mcp.morphic.com/v1/direct/tools/plan_media \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "steps": [
            { "id": "still", "tool_name": "generate_image", "arguments_json": "{\"prompt\":\"A red vintage bicycle\",\"aspect_ratio\":\"16:9\"}" },
            { "id": "clip", "tool_name": "generate_video", "arguments_json": "{\"prompt\":\"The bicycle rolls away\",\"duration_seconds\":8}", "depends_on": ["still"] }
          ]
        }
      }'

省略那些输出尚不存在的素材字段，并在 depends_on 中注明它们来自哪个步骤。
每个步骤都会得到其 validation、quote_status 和 estimated_credits。
结果还会给出 execution_order、known_estimated_credits、unquoted_step_ids 和 complete_estimate。当 complete_estimate 为 false 时，总和只是下限，不能作为预算。

密钥与余额

GET /v1/direct/me 返回发起调用的密钥、其上限和已用额度，以及组织的余额。任何密钥都可以调用它。

curl -s https://mcp.morphic.com/v1/direct/me \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "api_key": {
    "id": "01928e00-…",
    "name": "Order pipeline (prod)",
    "scopes": ["assets:read", "assets:write", "generations:write", "projects:read"],
    "expires_at": null,
    "credit_limits": {
      "total":   { "limit": 500000, "used": 182340, "remaining": 317660 },
      "monthly": { "limit": 100000, "used": 41200,  "remaining": 58800, "resets_at": "2026-11-01T00:00:00.000Z" },
      "daily":   { "limit": null,   "used": 2310,   "remaining": null,  "resets_at": "2026-10-26T00:00:00.000Z" }
    }
  },
  "organization": {
    "id": "01928d00-…",
    "plan": "enterprise",
    "remaining_credits": 1240000,
    "unlimited": false
  }
}

用量账目

GET /v1/direct/usage（权限范围 assets:read）返回该密钥产生的每一条账目条目，便于与你自己的记录对账。

查询参数	含义
`from`、`to`	`created_at` 的 ISO 8601 时间范围；默认为最近 30 天，最长 92 天
`generation_id`	仅返回单个生成任务的条目
`limit`	1 到 200，默认 50
`cursor`	上一页的 `next_cursor`

curl -s "https://mcp.morphic.com/v1/direct/usage?from=2026-10-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "usage": [
    { "id": "0192a7b3-…", "created_at": "2026-10-25T09:14:03.500Z", "kind": "charge",     "credits": 120, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } },
    { "id": "0192a7b4-…", "created_at": "2026-10-25T09:15:41.950Z", "kind": "settlement", "credits": -24, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } }
  ],
  "totals": { "charged": 120, "settled": -24, "refunded": 0, "net": 96 },
  "next_cursor": null
}

kind 为 charge、settlement 或 refund 之一；负的 credits 表示退还积分。
totals 覆盖整个筛选范围，而不仅仅是当前页。
在调用内返回结果的工具（analyze_video、analyze_audio、filmlab_edit）不会启动生成任务，因此其条目带有 generation_id: null，可通过 tool 区分。

如果您遇到任何问题或有任何疑问，欢迎随时联系我们。我们很乐意提供帮助。请发送邮件至 support@morphic.com.

积分与用量

生成任务如何扣费Copy Anchor Link

每个响应中的计费信息Copy Anchor Link

先报价再消费Copy Anchor Link

密钥与余额Copy Anchor Link

用量账目Copy Anchor Link

本页内容

生成任务如何扣费

每个响应中的计费信息

先报价再消费

密钥与余额

用量账目