Direct API
通过 HTTPS 从你自己的后端在 Morphic 中生成、编辑和管理图片、视频和音频。
Morphic Direct API 通过普通的 HTTPS 和 JSON，为你的后端提供与 Morphic MCP 服务器 为 AI 助手提供的相同的生成、编辑和素材库工具。你使用组织 API 密钥调用工具，每次付费调用都会报告其扣除的积分，你可以通过轮询或签名的 webhook 跟踪每个生成任务。
概览
| 基础 URL | https://mcp.morphic.com/v1/direct |
|---|---|
| 身份验证 | Authorization: Bearer mor_live_… |
| 格式 | JSON 请求体和响应体，UTF-8，每个请求最大 1 MB |
| ID | 你的数据使用 UUID v7 字符串，模型使用 mdl_…，音色使用来自 list_voices 的 UUID |
| 时间 | UTC 时间的 ISO 8601 格式，例如 2026-10-25T09:14:03.120Z |
| 计费单位 | Morphic 积分，以整数表示：与你的套餐和 Studio 消耗的积分相同 |
获取访问权限
Direct API 按组织开通，需受邀才能使用。开通之前，每次调用都会返回 403 direct_api_disabled。
- 请你的 Morphic 客户联系人为你的组织开通 Direct API。在你的订单签署后，Morphic 还会为你开启付费工具；在此之前，Direct API 的权限范围不会出现在 Studio 中，付费工具会返回
403 tool_not_available。 - 由组织的管理员在 Studio 的“设置 > API 密钥”中创建密钥，并代表组织接受 Morphic 使用条款，包括其中的开发者 API 部分。参见 创建密钥。
- 使用
Authorization: Bearer <secret>调用 API。
快速开始
找到输出应保存到的项目，启动一张图片的生成，然后等待它完成。
export MORPHIC_API_KEY=mor_live_9f2c… # created once in Studio > Settings > API keys
# 1. Which project should the output land in?
curl -s https://mcp.morphic.com/v1/direct/tools/list_projects \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {}}'
# 2. Start an image
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, soft morning light",
"aspect_ratio": "16:9",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f"
},
"webhook_id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
"metadata": { "order_id": "4411" }
}'
# 3. Wait for it (holds up to 45 s, returns the moment it finishes)
curl -s "https://mcp.morphic.com/v1/direct/generations/0192a7b3-…?wait=45" \
-H "Authorization: Bearer $MORPHIC_API_KEY"每个生成任务都会保存到你组织的 Morphic 素材库中你指定的项目里，就像在 Studio 中制作的一样。在 Studio 中，它会显示为由 API 创建，素材库的“创建者 > API”筛选器会列出你的 API 密钥制作或导入的所有内容。
端点
| 方法 | 路径 | 权限范围 | 作用 |
|---|---|---|---|
GET | /v1/direct/me | 无 | 密钥、其上限和已用额度，以及组织的余额 |
GET | /v1/direct/tools | 无 | 带 JSON Schema 的工具目录 |
GET | /v1/direct/tools/{tool_name} | 无 | 单个工具 |
GET | /v1/direct/openapi.json | 无 | OpenAPI 3.1 文档 |
POST | /v1/direct/tools/{tool_name} | 因工具而异 | 调用工具 |
GET | /v1/direct/generations/{id} | assets:read | 单个生成任务，可选长轮询 |
POST | /v1/direct/generations/batch-get | assets:read | 最多 10 个生成任务，可选长轮询 |
GET | /v1/direct/usage | assets:read | 账目条目和汇总 |
POST | /v1/direct/webhooks | generations:write | 注册端点 |
GET | /v1/direct/webhooks | assets:read | 列出端点 |
DELETE | /v1/direct/webhooks/{webhook_id} | generations:write | 删除端点 |
GET | /v1/direct/webhooks/{webhook_id}/events | assets:read | 投递日志 |
延伸阅读
身份验证
密钥、权限范围和积分上限
调用工具
请求、响应、计费和幂等性
生成任务
状态、轮询和批量读取
Webhook
生成任务完成时发送的签名通知
积分与用量
每次调用扣除的积分、/me 和 /usage
传入你自己的媒体
在任意媒体字段中通过 URL 提供你的文件
错误
所有错误代码及何时重试
限制
速率限制和大小限制
工具目录
所有工具及其所需的权限范围
模型
模型 ID、能力和选项
版本管理
v1 内可能发生的变化
如果您遇到任何问题或有任何疑问，欢迎随时联系我们。我们很乐意提供帮助。请发送邮件至 support@morphic.com.