图像与视频 API · 2026-10-11
一把媒体 Key,调用五类模型
通过 HTTP 提交任务,保存任务编号,查询完成后下载结果。客户使用自己的 GeiliAPI Key;模型和规格按下表填写。
先创建客户自己的 Key
控制台「API 密钥」→ 创建密钥 → 分组选择 AUAPI 图像与视频,计费来源选择 余额。该组目前不提供订阅计费。其他分组的旧 Key 不自动获得这五类媒体权限。设置测试额度、有效期和模型白名单,确保账户有余额。不要交付上游 Key、管理员登录 token 或历史测试 Key。
下方 cURL 使用完整路径。图片接口返回异步任务,需要显式轮询;直接调用普通 SDK 的 images.generate() 不能替代此流程。所有鉴权请求使用 Authorization: Bearer 客户Key。
模型与已开放规格
| 模型 | model(大小写敏感) | 参数 |
|---|---|---|
| GPT Image 2.5 | gpt-image-2.5 | resolution=1k、quality=low、n=1 |
| Nano Banana Pro | gemini-3-pro-image-preview | resolution=1k、n=1,不填 quality |
| Wan 3.0 | wan3.0-video | 480p 或 720p、5 秒、无声、16:9 |
| MiniMax H3 | MiniMax-H3 | 768p 或 2k、5 秒、含音频;示例不传比例 |
| Seedance 2.5 · 海外 260628 | dreamina-seedance-2-5-260628 | 720p、4 秒、无声、16:9 |
GPT 提示词最多 256 UTF-8 字节,其他四类最多 512 字节。首次验收使用短描述。此批接口开放文生图和文生视频;参考图、首尾帧、参考视频、编辑/延长、自动时长及其他规格尚未开放。Kling、Qwen Image、FLUX.2 暂未交付。Seedance 使用上述独立版本 ID,不能替换成旧 seedance-2.5。
售价按模型规格配置,个人折扣仅应用一次;以控制台当前价格和使用记录为准。人民币显示保留两位,内部美元账本保留原精度。
1. 验证鉴权和模型目录
在本机终端输入客户 Key(输入时不显示)。目录查询不生成媒体。下面后续命令共用这两个环境变量。
export GEILI_BASE='https://sub.geiliapi.com'
export GEILI_API_KEY="$(python3 -c 'import getpass; print(getpass.getpass("GeiliAPI Key: "))')"
curl --fail-with-body --silent --show-error \
"$GEILI_BASE/v1/models" \
-H "Authorization: Bearer $GEILI_API_KEY"预期 HTTP 200,data[].id 包含要调用的模型。如果缺少模型,先核对 Key 分组与白名单,再提交生成任务。
2. 实际生成一张图片
此操作会按当前规格售价扣费。每个新业务请求创建一个唯一幂等标识,并保存请求正文。不要给提交命令添加自动重试选项。
IMAGE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error \
"$GEILI_BASE/v1/images/generations/async" \
-H "Authorization: Bearer $GEILI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IMAGE_REQUEST_ID" \
--data '{"model":"gpt-image-2.5","prompt":"A red apple on a white table","resolution":"1k","quality":"low","n":1}'成功返回 HTTP 202,响应带 id/task_id 和 processing 状态。保存真实任务编号,每隔 3–5 秒执行一次查询:
IMAGE_TASK_ID='填入刚刚返回的任务编号'
curl --fail-with-body --silent --show-error \
"$GEILI_BASE/v1/images/tasks/$IMAGE_TASK_ID" \
-H "Authorization: Bearer $GEILI_API_KEY"只有 status=completed 才代表生成完成,下载返回的 image_url。下载结果 URL 不附带 API Key。Nano 使用相同路径,将请求正文改为:
{"model":"gemini-3-pro-image-preview","prompt":"A red apple on a white table","resolution":"1k","n":1}3. 实际生成一段视频
此操作同样会扣费。H3 示例为 768p、5 秒、含音频。
VIDEO_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body --silent --show-error \
"$GEILI_BASE/v1/videos/generations" \
-H "Authorization: Bearer $GEILI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $VIDEO_REQUEST_ID" \
--data '{"model":"MiniMax-H3","prompt":"A small boat moving slowly on a calm lake","resolution":"768p","duration":5,"generate_audio":true}'成功返回 HTTP 202。保存 id/task_id,使用提交时同一把 Key,每隔 3–5 秒查询:
VIDEO_TASK_ID='填入刚刚返回的任务编号'
curl --fail-with-body --silent --show-error \
"$GEILI_BASE/v1/videos/$VIDEO_TASK_ID" \
-H "Authorization: Bearer $GEILI_API_KEY"status=completed 后下载 video_url,也可调用 content 接口:
curl --fail-with-body --silent --show-error --location \
"$GEILI_BASE/v1/videos/$VIDEO_TASK_ID/content" \
-H "Authorization: Bearer $GEILI_API_KEY" \
--output result.mp4content 接口成功后以 HTTP 307 跳转到归档文件。cURL 默认不会将 Authorization 转发给不同主机;不要使用 --location-trusted。直接下载 video_url 时不附带 API Key。
其他两类视频使用相同提交、查询和下载路径,各自的请求正文为:
Wan 3.0
{"model":"wan3.0-video","prompt":"A small boat moving slowly on a calm lake","resolution":"480p","duration":5,"generate_audio":false,"aspect_ratio":"16:9"}Seedance 2.5 · 海外独立版本
{"model":"dreamina-seedance-2-5-260628","prompt":"A small boat moving slowly on a calm lake","resolution":"720p","duration":4,"generate_audio":false,"aspect_ratio":"16:9"}4. 客户交付验收
- 用客户自己的余额 Key 查目录,确认拟交付模型可见。
- 每类拟交付模型生成一个样本。HTTP 202 只表示接收;必须查询到 completed,文件能够下载并打开。
- 视频检查实际尺寸、时长和声音;如已安装 ffprobe,可执行
ffprobe -v error -show_streams -show_format result.mp4。 - 控制台「使用记录」按任务与 Key 核对实际规格、单次扣费、个人折扣一次、终态冻结金额释放。
- 检查无 Key、错误 Key、错误规格、其他 Key 查询任务均被拒绝。不要用这些用例再次生成付费样本。
- 保存任务编号、幂等标识、原正文、HTTP 状态与 request ID,不在日志记录 Key。及时保存结果;响应提供 expires_at,不能依赖链接永久有效。测试结束仅撤销临时测试 Key。
异常时怎么处理
提交超时不代表没有生成
拿到任务编号后,只查询原任务。没有拿到编号时,保留原请求与幂等标识交由支持核对,不自动更换 Key、幂等标识或供应商再次提交。一个幂等标识只对应同一 Key 的同一业务请求与完全相同的正文。
| HTTP/情况 | 检查与处理 |
|---|---|
| 400 | 模型 ID、已开放规格、字段类型、提示词字节数。 |
| 401 | Bearer 鉴权、Key 是否撤销或过期。 |
| 403/404 | Key 分组、模型白名单、任务是否属于提交时同一 Key。 |
| 402/额度错误 | 客户余额、Key 额度;若错误来自供应商余额,联系支持。 |
| 409 | 幂等正文冲突或内容未就绪,先查询原任务。 |
| 429 | 等待 Retry-After;已接收任务继续查询。 |
| 5xx/断网/未知状态 | 保存请求标识,查询原任务或联系支持,避免重复生成。 |
错误响应的包装可能不同,以实际 HTTP 状态和返回的 error 信息为准。