外观
5 分钟接入：API Key 与鉴权
接入知梦只需要三件事：选对 Base URL、把 Key 放在服务端、按对应协议发第一个请求。图片与音频是同步接口，一次请求直接返回结果；视频是异步任务接口，创建后需要轮询。下面用 gpt-image-2 和 wan3.0-video 各跑通一遍。
1. 选对 Base URL
| 用途 | Base URL | SDK baseURL | 覆盖能力 |
|---|---|---|---|
| 图片、音频 | https://api.zmoapi.cn | https://api.zmoapi.cn/v1 | ChatGPT / Gemini / Grok / Seedream 生图、Gemini TTS、Lyria、Suno |
| 视频 | https://movie.zmoapi.cn | 无 OpenAI SDK 入口，直接请求 /v1/videos | Grok / MiniMax H3 / Wan 3.0 / SD / Seedance 2.0 / 2.5 / Veo / Omni |
两个地址是不同的账号体系：图片站的 Key 不能调视频接口，余额也不通用。使用 OpenAI SDK 时只填 SDK baseURL，SDK 会自己补 /v1/... 路径；用 curl 时路径要写全。
先确认走哪套协议
ChatGPT、Gemini OpenAI 兼容、Seedream 与音频模型走 OpenAI 风格接口；Gemini 原生协议走 /v1beta/models/{model}:generateContent；Grok 与视频任务走各自的原生接口。协议细节见 ChatGPT 协议、Gemini 原生协议、视频概览。
2. 把 Key 放在服务端
所有请求只用一个头：
http
Authorization: Bearer ZHM_API_KEY
Content-Type: application/jsonKey 必须保存在服务端环境变量或密钥管理服务里（例如 ZHM_API_KEY）。不要写进前端页面、移动端包体、公开仓库或浏览器可见的配置；一旦泄漏，去平台重新生成并弃用旧 Key。代理转发时同样不要把它回显给客户端。
JSON 请求用 application/json；图片编辑这类上传文件的请求用 multipart/form-data，boundary 交给 curl 或 SDK 自动生成，不要手写固定值。
3. 第一次生图（curl 直接存盘）
bash
curl -s 'https://api.zmoapi.cn/v1/images/generations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗边，午后阳光穿过百叶窗，写实摄影",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"n": 1
}' \
| jq -r '.data[0].b64_json' \
| base64 --decode > image.png输出尺寸由 size 决定，模型名里的 1K / 2K / 4K 后缀只用于路由和计费档位。gpt-image-2 的 1K 档为 ¥0.025 / 张，完整价格见 价格与模型。
4. 响应长什么样
GPT Image 系列返回 Base64，另外部分图片模型返回临时 URL：
json
{
"created": 1784300000,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(省略)"
}
]
}读 data[0].b64_json 解码即可；若响应里只有 data[0].url，先下载再转存到自己的对象存储。返回的 URL 可能是签名地址，会提前失效，不要当作永久链接写进数据库。
5. 视频任务：创建 → 轮询 → 取结果
视频不会在创建请求里返回成片，流程固定为三步。
创建任务（Grok 视频用 /v1/videos/generations，其余视频模型用 /v1/videos）：
bash
curl 'https://movie.zmoapi.cn/v1/videos' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"model": "wan3.0-video",
"prompt": "电影感镜头，一辆复古跑车穿过雨后的霓虹街道，镜头缓慢跟随",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9"
}'json
{
"id": "task_EXAMPLE",
"task_id": "task_EXAMPLE",
"status": "queued",
"progress": 0
}保存任务 ID，然后轮询同一个任务：
bash
curl 'https://movie.zmoapi.cn/v1/videos/task_EXAMPLE' \
-H 'Authorization: Bearer YOUR_API_KEY'status | 含义 | 该做什么 |
|---|---|---|
queued / pending | 排队中 | 继续等待，不要重建任务 |
in_progress / processing | 生成中 | 每 10–20 秒查一次 |
completed | 已完成 | 读取 content.url，立刻下载 |
failed | 生成失败 | 停止轮询，读 error.message 定位原因 |
完成后的响应大致如下，成片地址优先读 content.url，video_url、result_url、output[0] 为兼容字段：
json
{
"id": "task_EXAMPLE",
"status": "completed",
"progress": 100,
"content": {"url": "https://example.com/result.mp4"}
}三条硬规则：progress: 100 不等于成功，只以 status: "completed" 加可用地址为准；提交超时或连接断开不代表任务没建成，先查任务记录再决定是否重提，重复创建会重复扣费；成片链接有有效期，生成后尽快转存。各模型字段不同（Veo / Omni 不支持秒数和分辨率，Seedance 2.5 用顶层 prompt / ratio / resolution），抄别人的请求体前先看对应模型页。
6. 第一个请求就报错
| 现象 | 先看这里 |
|---|---|
401 未授权 | Authorization 是否带 Bearer 前缀、Key 是否含空格或换行 |
403 禁止访问 | 当前 Key 的分组是否包含该模型 |
404 找不到 | Base URL 是否选错站、路径是否少了 /v1、模型 ID 是否拼错 |
429 限流 | 降低并发，按退避重试；不要并发重试 |
视频任务 failed | 读 error.message，参考素材 URL 是否公网可直连 |
完整的状态码对照、各协议错误体差异和视频失败排查见 错误排查。仍无法定位时，带上模型 ID、HTTP 状态码和 Request ID 联系 技术支持。