调用工具
用同一种请求格式调用任意 Direct API 工具，读取其结果和计费信息，并借助 Idempotency-Key 安全地重试付费调用。
每项能力都是一个工具，调用方式都相同：POST /v1/direct/tools/{tool_name}。工具目录 列出了所有工具。
请求
| 请求头 | 必填 | 值 |
|---|---|---|
Authorization | 是 | Bearer <key> |
Content-Type | 是 | application/json |
Idempotency-Key | 付费调用建议使用 | 参见 幂等性 |
{
"input": { },
"webhook_id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
"metadata": { "order_id": "4411", "customer": "acme" }
}| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
input | object | 是 | 工具的参数，按其 input_schema 校验。对于不接受参数的工具，发送 {}。每个会创建内容的工具（生成任务、导入、上传、时间线）都需要 project_id，可从 list_projects 获取。 |
webhook_id | string 或 null | 否 | 一个已注册的 webhook 端点，当此调用启动的每个生成任务达到最终状态时会通知它。仅对 returns_generation: true 的工具有意义；在其他工具上会被拒绝。 |
metadata | object 或 null | 否 | 最多 20 个字符串键（不超过 40 个字符），值为字符串（不超过 500 个字符）。保存在此调用启动的每个生成任务上，并在每次读取和每个 webhook 中原样返回。Morphic 从不解读其内容。 |
一个带幂等键的完整调用：
curl -s https://mcp.morphic.com/v1/direct/tools/generate_image \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4411-hero-image" \
-d '{"input": {"prompt": "A red vintage bicycle against a pastel wall", "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f"}, "metadata": {"order_id": "4411"}}'在 Morphic 服务器上渲染视频的工具（video_compose、video_* 变换工具和 burn_subtitles）暂不接受 webhook_id 或 metadata。设置其中任何一个时，它们会返回 422 tool_refused；请改为轮询它们的生成任务。
响应
每个成功响应都使用相同的外层结构。工具自身的输出位于 result 中，格式由其 output_schema 描述。
{
"request_id": "0192a7b3-91d0-7c55-b1aa-6e5f4c3b2a10",
"tool": "generate_image",
"result": {
"generation_id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
"generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"],
"status": "queued",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
"project_name": "Spring campaign",
"file_id": "01928f4e-6c8d-7a10-b2c3-d4e5f6a7b8c9",
"model_id": "mdl_3hv8tq1nzc6e",
"estimated_credits": 8,
"credits_settle_on_output_duration": false
},
"billing": {
"credits_charged": 8,
"credits_are_final": false,
"credits_settle_on_output_duration": false,
"generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"]
}
}| 状态 | 何时返回 |
|---|---|
202 Accepted | 工具启动了一个或多个生成任务（returns_generation: true）；通过 轮询 或 webhook 跟踪它们 |
200 OK | 工具在调用内完成（列表、目录、报价、分析），或是幂等重放 |
计费块
每个成功响应都包含 billing，免费调用也不例外。
| 调用类型 | billing.credits_charged | credits_are_final |
|---|---|---|
| 免费调用：列表、目录、报价、状态读取 | 0 | true |
启动生成任务的调用（202） | 启动时为每个已启动的生成任务扣除的积分之和 | false |
在请求内完成的付费调用（analyze_video、analyze_audio、filmlab_edit） | 其扣除的积分 | true |
被拒绝的调用（4xx） | 没有 billing 块；不扣除任何积分 |
该块报告的是调用返回时扣除的积分。退款和结算会在之后发生，并显示在生成任务上，而不会出现在原始响应中。响应还带有 Morphic-Credits-Charged: <integer>，便于在你的网关处记录日志。积分与用量 说明了生成任务如何扣费、结算和退款。
工具拒绝
当输入格式正确但无法运行时（你的套餐不包含的模型、模型不提供的宽高比、类型错误的素材），调用会返回 422 tool_refused。消息会指出字段、值以及可以使用的值。没有启动任何任务，也没有扣除任何积分。
{
"description": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. Offered: 1:1, 4:3, 3:4, 16:9, 9:16. Models offering 21:9 for text_to_image: mdl_9wd4mf2kqs7b.",
"code": "tool_refused",
"data": { "request_id": "0192a7b3-…", "tool": "generate_image" },
"error": { "error_code": "TOOL_REFUSED", "message": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. …" }
}部分启动
variations 大于 1 的调用会为每个变体启动一个生成任务。如果较早的变体已启动后，后面的某个变体被拒绝：
- 响应仍然是
202，result.partial_failure会说明发生了什么。 result.generation_ids只列出已启动的任务，billing也只计算已启动的任务。- 只重试缺失的变体。
幂等性
网络故障可能发生在请求已发出、但响应尚未到达之时。要安全地重试付费调用，请发送 Idempotency-Key 请求头。使用你自己的作业 ID 或订单 ID。
Idempotency-Key: order-4411-hero-image- 带有某个键的第一个请求正常运行。
- 24 小时内使用相同的键、工具和请求体进行重试，不会再次运行。它会返回
200和原始响应体，包括原始的generation_ids和billing，并且不会再扣除任何积分。其Morphic-Credits-Charged响应头为0。 - 相同的键搭配不同的工具或请求体，会返回
409 idempotency_conflict。 - 原始请求仍在运行时重试，会返回
409 idempotency_in_progress。 - 如果付费调用的原始请求失败（
5xx），或在可能已经运行之后始终没有响应，对它的重试会返回409 idempotency_outcome_unknown。它在同一个键下永远不会再次运行：请先检查其结果，然后使用新键。 - 键的作用域限于发送它的 API 密钥，最长 200 个字符。
免费调用同样接受此请求头，但很少需要。
在 5xx 之后重试付费调用
返回 500、503 或 504 的付费调用，可能在失败前已经启动了工作并扣除了积分。
- 用
list_generations，或按时间筛选的GET /v1/direct/usage，检查该调用做了什么。 - 只为尚未启动的工作发送新的
Idempotency-Key。
如果完全没有收到响应（连接中断），请使用相同的键重试：你会得到已保存的响应，或者在它仍在运行时得到 409 idempotency_in_progress。
如果您遇到任何问题或有任何疑问，欢迎随时联系我们。我们很乐意提供帮助。请发送邮件至 support@morphic.com.