GeiliAPI 接入手册

图像与视频 API · 2026-10-11

一把媒体 Key,调用五类模型

通过 HTTP 提交任务,保存任务编号,查询完成后下载结果。客户使用自己的 GeiliAPI Key;模型和规格按下表填写。

打开纯文本说明 网页检查效果

先创建客户自己的 Key

控制台「API 密钥」→ 创建密钥 → 分组选择 AUAPI 图像与视频,计费来源选择 余额。该组目前不提供订阅计费。其他分组的旧 Key 不自动获得这五类媒体权限。设置测试额度、有效期和模型白名单,确保账户有余额。不要交付上游 Key、管理员登录 token 或历史测试 Key。

HTTP 请求根地址https://sub.geiliapi.com
客户端 Base URLhttps://sub.geiliapi.com/v1

下方 cURL 使用完整路径。图片接口返回异步任务,需要显式轮询;直接调用普通 SDK 的 images.generate() 不能替代此流程。所有鉴权请求使用 Authorization: Bearer 客户Key。

模型与已开放规格

模型model(大小写敏感)参数
GPT Image 2.5gpt-image-2.5resolution=1k、quality=low、n=1
Nano Banana Progemini-3-pro-image-previewresolution=1k、n=1,不填 quality
Wan 3.0wan3.0-video480p 或 720p、5 秒、无声、16:9
MiniMax H3MiniMax-H3768p 或 2k、5 秒、含音频;示例不传比例
Seedance 2.5 · 海外 260628dreamina-seedance-2-5-260628720p、4 秒、无声、16:9

GPT 提示词最多 256 UTF-8 字节,其他四类最多 512 字节。首次验收使用短描述。此批接口开放文生图和文生视频;参考图、首尾帧、参考视频、编辑/延长、自动时长及其他规格尚未开放。Kling、Qwen Image、FLUX.2 暂未交付。Seedance 使用上述独立版本 ID,不能替换成旧 seedance-2.5。

售价按模型规格配置,个人折扣仅应用一次;以控制台当前价格和使用记录为准。人民币显示保留两位,内部美元账本保留原精度。

1. 验证鉴权和模型目录

在本机终端输入客户 Key(输入时不显示)。目录查询不生成媒体。下面后续命令共用这两个环境变量。

HTTP API 示例
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. 实际生成一张图片

此操作会按当前规格售价扣费。每个新业务请求创建一个唯一幂等标识,并保存请求正文。不要给提交命令添加自动重试选项。

HTTP API 示例
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 秒执行一次查询:

HTTP API 示例
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 使用相同路径,将请求正文改为:

HTTP API 示例
{"model":"gemini-3-pro-image-preview","prompt":"A red apple on a white table","resolution":"1k","n":1}

3. 实际生成一段视频

此操作同样会扣费。H3 示例为 768p、5 秒、含音频。

HTTP API 示例
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 秒查询:

HTTP API 示例
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 接口:

HTTP API 示例
curl --fail-with-body --silent --show-error --location \
  "$GEILI_BASE/v1/videos/$VIDEO_TASK_ID/content" \
  -H "Authorization: Bearer $GEILI_API_KEY" \
  --output result.mp4

content 接口成功后以 HTTP 307 跳转到归档文件。cURL 默认不会将 Authorization 转发给不同主机;不要使用 --location-trusted。直接下载 video_url 时不附带 API Key。

其他两类视频使用相同提交、查询和下载路径,各自的请求正文为:

Wan 3.0

HTTP API 示例
{"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 · 海外独立版本

HTTP API 示例
{"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. 客户交付验收

  1. 用客户自己的余额 Key 查目录,确认拟交付模型可见。
  2. 每类拟交付模型生成一个样本。HTTP 202 只表示接收;必须查询到 completed,文件能够下载并打开。
  3. 视频检查实际尺寸、时长和声音;如已安装 ffprobe,可执行 ffprobe -v error -show_streams -show_format result.mp4。
  4. 控制台「使用记录」按任务与 Key 核对实际规格、单次扣费、个人折扣一次、终态冻结金额释放。
  5. 检查无 Key、错误 Key、错误规格、其他 Key 查询任务均被拒绝。不要用这些用例再次生成付费样本。
  6. 保存任务编号、幂等标识、原正文、HTTP 状态与 request ID,不在日志记录 Key。及时保存结果;响应提供 expires_at,不能依赖链接永久有效。测试结束仅撤销临时测试 Key。

异常时怎么处理

提交超时不代表没有生成

拿到任务编号后,只查询原任务。没有拿到编号时,保留原请求与幂等标识交由支持核对,不自动更换 Key、幂等标识或供应商再次提交。一个幂等标识只对应同一 Key 的同一业务请求与完全相同的正文。

HTTP/情况检查与处理
400模型 ID、已开放规格、字段类型、提示词字节数。
401Bearer 鉴权、Key 是否撤销或过期。
403/404Key 分组、模型白名单、任务是否属于提交时同一 Key。
402/额度错误客户余额、Key 额度;若错误来自供应商余额,联系支持。
409幂等正文冲突或内容未就绪,先查询原任务。
429等待 Retry-After;已接收任务继续查询。
5xx/断网/未知状态保存请求标识,查询原任务或联系支持,避免重复生成。

错误响应的包装可能不同,以实际 HTTP 状态和返回的 error 信息为准。

已复制