# GeiliAPI 图像与视频 API(2026-10-11) 适用于 AUAPI 图像与视频分组的客户余额 Key。使用客户自己的 GeiliAPI Key;不要使用上游 ArtsAPI Key、管理员登录 token 或历史测试 Key。创建 Key 时选择「AUAPI 图像与视频」,计费来源选择余额。当前该组不提供订阅计费。其他分组的旧 Key 不自动获得此媒体账户的权限。 HTTP API root: https://sub.geiliapi.com SDK base_url(需要自动补 /v1 的客户端): https://sub.geiliapi.com/v1 Authorization: Bearer ${GEILI_API_KEY} Content-Type: application/json 客户先执行 GET /v1/models。data[].id 是当前 Key 可访问的模型目录。模型 ID 大小写敏感;以下是当前已开放的型号和规格,目录存在不代表所有参数组合均可调用: 1. GPT Image 2.5: gpt-image-2.5; resolution=1k, quality=low, n=1。 2. Nano Banana Pro: gemini-3-pro-image-preview; resolution=1k, n=1; 不填写 quality。 3. Wan 3.0: wan3.0-video; resolution=480p 或 720p; duration=5; generate_audio=false; aspect_ratio=16:9。 4. MiniMax H3: MiniMax-H3; resolution=768p 或 2k; duration=5; generate_audio=true; 示例不传 aspect_ratio。 5. Seedance 2.5 海外独立版本: dreamina-seedance-2-5-260628; resolution=720p; duration=4; generate_audio=false; aspect_ratio=16:9。不要改成旧 seedance-2.5 或假定其他版本等价。 GPT 提示词最多 256 UTF-8 字节,其他四类最多 512 UTF-8 字节。首次验收使用短提示词。图片当前使用文生图异步接口;视频使用文生视频异步接口。本批 Geili 接口暂不开放参考图/首尾帧/参考视频、视频编辑/延长、自动时长、未列出的分辨率和声音组合。Kling、Qwen Image、FLUX.2 尚未开放。不要推断上游功能均已通过本接口开放。 图片创建: POST /v1/images/generations/async Idempotency-Key: 每个新业务请求唯一且持久化的 UUID {"model":"gpt-image-2.5","prompt":"A red apple on a white table","resolution":"1k","quality":"low","n":1} Nano 请求正文: {"model":"gemini-3-pro-image-preview","prompt":"A red apple on a white table","resolution":"1k","n":1} 创建成功返回 HTTP 202(表示任务已接收,尚未生成完成)。响应包含 id/task_id、status、created_at、expires_at;图片响应还包含 poll_url。查询图片: GET /v1/images/tasks/{task_id} 使用提交时同一把 Key。终态 completed 时 image_url 为下载地址;result.data[] 也可包含结果。下载结果 URL 时不附带 GeiliAPI Authorization。 视频创建: POST /v1/videos/generations Idempotency-Key: 每个新业务请求唯一且持久化的 UUID {"model":"MiniMax-H3","prompt":"A small boat moving slowly on a calm lake","resolution":"768p","duration":5,"generate_audio":true} Wan 请求正文: {"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 请求正文: {"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"} 视频创建成功返回 HTTP 202,包含 id/task_id。查询视频: GET /v1/videos/{task_id} 终态 completed 时 video_url 为下载地址;或用同一 Key 请求 GET /v1/videos/{task_id}/content,成功后 HTTP 307 跳转至归档结果。curl -L 默认不会将 Authorization 转发给不同主机;不要使用 --location-trusted。直接下载 video_url 不附带 GeiliAPI Authorization。 每隔 3–5 秒查询,支持 processing、completed、failed;其他未知/对账状态继续查询原任务并联系支持。查询使用提交任务时的同一用户和同一 Key,其他 Key 无权读取该任务。保存任务 ID、Idempotency-Key、请求正文、HTTP 状态和 request ID;不要在日志中保存 Key。 提交超时/断网/5xx 不能当作“未生成”。如果拿到了任务 ID,只查询原任务;没有任务 ID 时保留原请求和幂等标识交由支持核对,禁止自动换幂等标识/Key/供应商再次生成。幂等标识仅用于同一业务请求和完全相同的正文,不跨 Key 复用。不要在 create 命令使用 curl --retry/--retry-all-errors。 错误处理: 400: 检查准确模型 ID、已开放规格、提示词 UTF-8 字节数、类型和不支持的字段。 401: Key 无效、已撤销、过期,或没有发送正确的 Bearer header。 403/404: 检查 Key 分组/模型白名单和任务归属;随机或其他 Key 的任务不应可读。 402 或余额/额度错误: 检查客户余额、Key 额度及有效期。供应商余额不足不能靠客户反复提交解决。 409: 幂等正文冲突或视频内容尚未就绪;先查询任务。 429: 等待 Retry-After;已接收的任务只轮询,不重复提交。 5xx/超时: 保留原任务/请求标识并查询/核对,不能自动重复生成。 创建和轮询均以返回的实际 HTTP 状态和 error 信息为准;错误 JSON 不保证只有一种包装层。 验收顺序(真实生成会按当前规格售价扣费): 1. 新建客户测试余额 Key,额度限制为一次测试所需金额;不更改现有客户 Key。 2. GET /v1/models 成功并看到拟交付模型;这一步不生成媒体。 3. 使用 GPT 1k/low/n=1 创建一个图片任务,202 后轮询到 completed,下载并打开图片。 4. 使用 H3 768p/5 秒/含音频创建一个视频任务,202 后轮询到 completed,下载并打开视频;检查尺寸、时长、音频。Wan、Nano、Seedance 按各自正文逐个验收,不能仅测试一个模型就宣称全部成功。 5. 控制台使用记录按任务和 Key 核对实际规格、仅一次扣费、个人折扣仅一次、终态冻结余额释放。CNY 显示可保留两位,账本 USD 内部精度不截断。 6. 测试无 Key、错误 Key、错误规格、其他 Key 查询任务的拒绝行为;这些不能触发新付费生成。 7. 客户验收成功后保留其正式 Key;仅撤销临时测试 Key。任务响应有 expires_at,及时下载并自行保存结果,不依赖结果链接永久有效。 现有上线证据包括真实生成、R2 归档、完整解码、单次个人折扣结算和 hold 归零。本文提供调用契约,不代替客户自己的账户/额度/网络验收。