# Oairegbox API 文档中心（完整纯文本版）

> 由 https://docs.oairegbox.cc/ 自动转换，生成于 2026-11-10。以网页为准。


---

# 从一个模型名开始，完成稳定的媒体生成接入。
来源：https://docs.oairegbox.cc/#sec-home

## 从一个模型名开始，完成稳定的媒体生成接入。
Oairegbox 是 OpenAI 兼容的多模型 API 聚合网关。你用一把令牌、同一套接口，就能调用视频、图像、文本和音频模型。它不是账号注册平台，也不提供短信验证码或接码服务。接入地址是 api.oairegbox.cc。
先选择模型原厂与能力，再按详情页确认令牌分组、请求参数和异步任务结果。所有既有模型文档都保留在本次改版中。

### 创建令牌
在控制台创建 API Key，并确认目标模型对应分组已开通。

### 提交任务
视频统一走 POST /v1/videos ，参数以对应模型章节为准。

### 读取结果
用任务 ID 轮询，完成后读取脱敏后的 video_url 。

### 视频生成，按原厂与自定义线路发现
模型原厂决定能力；令牌分组和路由则在每个模型详情页中确认。自定义线路单独标注，不与官方原厂链路混排。

#### Google
Veo 3.1、Omni 与 Veo-Clean，覆盖文生、图生和部分 V2V。

#### 字节跳动
Seedance 2.0 与 2.5 官方直连，覆盖生成、全能参考与 V2V；另有 Seedream 图像生成。

#### xAI
Grok Imagine 视频（1.0 / 1.5 / 6 秒定档共 3 个模型，分辨率用参数控制），支持文本和参考图驱动。

#### Adobe
Firefly Veo、Seedance、Kling、Gemini Omni 与 GPT Image 2，统一由 Adobe Firefly 分组接入。

#### MiniMax
MiniMax H3 支持原生音频、参考图、首尾帧与参考视频驱动。

#### 阿里云百炼
通义万相 3.0 视频（全能参考版 + 优速版 prime），全多模态参考（文生/首尾帧/多图/图视音频/文档网页链接），480p/720p/1080p 按秒计费；另有通义千问 Qwen 图像生成（文生图 / 图生图，按张计费）。

#### 快手可灵
Kling 3.0 / Kling-v3 官方直连视频生成，支持文生视频、首尾帧、多图融合与图视混合生成，按秒计费、默认有声。

#### OpenAI
GPT Image 2.6（1K/2K·Flare/Sunburst·支持动态 GIF 与 SVG）、GPT Image 2（1K/2K/4K）与 2.5 图像生成全谱系，无水印。

#### DeepSeek
DeepSeek V4.1 Flash 对话模型，OpenAI 兼容，1M 上下文，支持缓存命中优惠；按北京时间高峰 / 空闲两档计价，周末全天按空闲价。

#### 自定义厂商
Seedance 2.0 mini / fast / standard 与 Seedance 2.5 自定义线路，720p 高清，与字节跳动官方链路分开维护。

#### Meta Muse
muse-fast 全模态极速分组：覆盖云端 Agent 对话、图像生成/编辑、视频生成、Avocado v2 语音合成/转写与 Live 实时语音，支持云端沙盒会话粘性。

---

# 把一个 SKILL.md 交给 AI，让它按真实接口完成接入。
来源：https://docs.oairegbox.cc/#sec-skill

## 把一个 SKILL.md 交给 AI，让它按真实接口完成接入。
适用于 Codex、Claude Code、Cursor、Windsurf、Cline 等工具。技能文件会先读取项目环境变量，再发现此令牌实际可见的模型，按本站模型页选择正确的调用方式。

### 一个文件，覆盖接入时最常见的错误点
不让 AI 猜模型名、分组、视频轮询或素材字段；模型列表由令牌实时读取，模型参数与价格仍回到本站对应章节核对。
```
name: oairegbox-api-gateway
description: Integrate the gateway

1. Read .env
2. GET /v1/models
3. Pick visible model ID
4. Follow model documentation
5. Poll existing video task

Never expose API keys.
```

### 开始使用
下载技能文件后，与下方提示词一起交给 AI。它会将文件放到项目技能目录，并保留原始内容。

#### 把 SKILL.md 放进项目
先下载文件，再和这段提示一并发送给你的 AI 编程工具。它会按所用工具的项目目录创建技能文件夹。
```
这是 OAIREGBOX 的 API 接入技能文件 SKILL.md。请把它放到本项目的技能目录：
Claude Code 放 .claude/skills/oairegbox-api-gateway/；Cursor 放 .cursor/skills/oairegbox-api-gateway/；
Windsurf 放 .windsurf/skills/oairegbox-api-gateway/；Cline 放 .cline/skills/oairegbox-api-gateway/；
其它工具放项目根目录 ai-gateway-skill/。目录不存在就新建，文件内容原样写入，完成后告诉我实际路径。
```

#### 把令牌存入 .env
令牌只保存在项目本地环境变量，AI 后续从 `.env` 读取，不应再次要求你在对话中粘贴密钥。
```
我的 OAIREGBOX API Key 是：【粘贴 Key】。请把它写进项目根目录 .env：
OAIREGBOX_API_BASE_URL=https://newapi-2.oairegbox.cc
OAIREGBOX_API_KEY=【粘贴 Key】
如果已有 .env，只追加缺失变量，不要覆盖其它内容；确认 .env 已在 .gitignore 中。以后从 .env 读取，不要在代码、日志或浏览器端暴露 Key。
```

#### 先发现模型，再写接入代码
AI 会先用令牌调用 `/v1/models`，只使用实际可见的模型 ID；视频、图像与多参考素材均回到对应模型页核对参数。
```
请读取 OAIREGBOX 的 SKILL.md，先从 .env 取配置并 GET $OAIREGBOX_API_BASE_URL/v1/models。
按视频、图像、音频、文本分类列出我当前令牌可用的模型；不要猜模型名或价格。之后根据我的需求选择模型并给出接入方案，生成类请求先等我明确确认。
```

### 可以直接交给 AI 的需求
以下提示都先要求 AI 读取技能文件和令牌可见模型，避免项目被写入无法调用的模型名。
```
读一下 OAIREGBOX 的 SKILL.md，从 .env 拉一遍 /v1/models。按对话、图片、视频、音频分类列出当前令牌可用的模型，并各给一个适用场景。
```
```
我的项目已经使用 OpenAI SDK。读取 OAIREGBOX 的 SKILL.md，把 base_url 和 API Key 改为从 .env 读取，其它业务代码尽量不动；先只用 GET /v1/models 验证配置，不要发起付费生成。
```
```
读取 OAIREGBOX 的 SKILL.md 和目标视频模型页。帮我做一个图生视频工具：提交任务后按 4 秒间隔轮询同一个 task_id，完成时保存响应中的 video_url；失败时保留 task_id 和错误信息。
```
```
从 .env 查询 OAIREGBOX 令牌使用情况，读取 /api/usage/token/。告诉我可用额度、是否有限制模型、是否设置过期时间；不要把 Key 输出到终端或日志。
```

### 给 AI 的接入技能
下载后交给 AI 编程工具。文件只引用真实的模型、视频、用量和素材能力。

### 本页

### 接入真值

---

# 调用入口
来源：https://docs.oairegbox.cc/#sec-call-entry

## 调用入口
按 SDK 与任务类型选择协议。文本、Responses、Anthropic、图像、视频和音频使用不同的公开入口，模型名必须来自当前令牌可见列表。

### 对话补全
所有可用的 Chat 模型共用 OpenAI Chat Completions 请求体。换 model 即切换模型；长响应或推理场景建议开启 stream: true 。

#### Chat Completions
OpenAI 兼容文本、多模态和工具调用入口。

##### 核心参数
| 参数 | 位置 | 必填 | 说明 |
| model | body | 是 | 来自 GET /v1/models 的可见模型 ID。 |
| messages | body | 是 | OpenAI 消息数组；多模态字段以目标模型章节为准。 |
| stream | body | 否 | true 时按 SSE 输出。 |
| temperature / max_tokens / tools | body | 否 | 按 OpenAI 规范传递，模型支持度不同。 |

##### 请求示例
```
curl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"用一句话介绍你自己"}],"stream":true}'
```

### 原生协议

#### OpenAI Responses
面向新版 OpenAI SDK、Codex 与 Agent 工具链的原生输入格式。
| 参数 | 必填 | 说明 |
| model | 是 | 当前令牌可见的 Chat 模型。 |
| input | 是 | 字符串或 Responses 输入项数组。 |
| instructions / tools / stream | 否 | 按 Responses 规范传递。 |
```
curl "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","input":"列出三个使用本 API 的理由"}'
```

#### Anthropic Messages
面向 Claude SDK 的原生 Messages 协议。
| 参数 | 必填 | 说明 |
| model | 是 | 可见模型 ID；优先使用 Claude 系列模型。 |
| max_tokens | 是 | Anthropic Messages 规范必填。 |
| messages | 是 | Anthropic 消息数组。 |
```
curl "$BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```

### 图像生成与编辑

#### Images
同步返回图片 URL 或 Base64。模型专属尺寸、质量与参考素材字段必须查看模型详情页。
| 参数 | 必填 | 说明 |
| model / prompt | 是 | 模型 ID 与生成描述。 |
| n / size / quality / response_format | 否 | 仅在目标模型支持时传递。 |
```
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","prompt":"一只戴帽子的柴犬","n":1,"size":"1024x1024"}'
```

### 视频生成

#### Async Video
当前规范视频入口。模型可能接受 JSON、Base64、URL 或 multipart，不能跨模型复制素材字段。
| 参数 | 必填 | 说明 |
| model | 是 | 来自可见模型列表。 |
| prompt | 通常是 | 视频描述；不同模型的规则不同。 |
| seconds / size / images / input_reference | 模型相关 | 按目标模型页选择，不能假设通用支持。 |
```
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","prompt":"雨夜霓虹街道，镜头缓慢推进","aspect_ratio":"16:9"}'
```

### 音频入口

#### Speech / Transcription / Translation
标准 OpenAI 音频入口；音乐模型的调用方式以对应模型详情页为准。

#### 已开放路由
语音合成、音频转写与翻译均有 OpenAI 风格入口。

#### 音乐异步统一入口
通用 /v1/audio/generations / /v1/media/generate 统一入口待更新；当前请使用上方已开放的音频路由。

### 本页

### 当前边界

---

# 任务与轮询
来源：https://docs.oairegbox.cc/#sec-task-polling

## 任务与轮询
当前视频与异步媒体任务使用视频任务 ID 查询。任务已受理后只轮询同一个 ID，不因客户端等待超时重复提交。

### 状态速查
当前规范返回四个客户可处理状态。不同来源的原始状态在网关内部映射，客户不需要识别底层状态名。

#### queued
任务已受理，等待执行。保留任务 ID。

#### in_progress
任务正在处理。进度字段仅作参考。

#### completed
读取结果 URL，停止轮询。

#### failed
读取错误并保留任务 ID 供排查。

### 查询任务

#### 查询当前令牌的任务
任务归属当前用户。不能查询其他令牌用户的任务。
| 参数 | 位置 | 必填 | 说明 |
| task_id | path | 是 | 提交时返回的公开任务 ID。 |
```
curl "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

##### 完成响应的兼容读取顺序
```
status = response["status"]
if status == "completed":
    url = response.get("video_url") \
        or response.get("data", [{}])[0].get("url") \
        or response.get("metadata", {}).get("url")
elif status == "failed":
    error = response.get("error") or response.get("fail_reason")
```

### 轮询与下载规则

#### 轮询已有任务
建议每 3–5 秒查询一次。 queued 与 in_progress 时继续轮询，不要重复 POST。

#### 结果 URL
完成后优先使用响应结果地址；已就绪的媒体也可通过内容路径下载。

#### 统一任务契约
统一 /v1/tasks/{task_id} （ is_final 、 output_url 、进度与统一错误对象）待更新。

#### 任务类型统一
音乐、语音、图像异步任务的统一查询待更新；当前以各模型实际文档为准。

### 本页

### 终态原则

---

# 模型接口与发现
来源：https://docs.oairegbox.cc/#sec-model-discovery

## 模型接口与发现
先查询当前令牌能使用的模型，再从模型详情页确认参数、素材规则和价格。模型名、可见性和价格都不应由 AI 或客户端猜测。

### 当前模型列表

#### 令牌可见模型
OpenAI 兼容列表。返回值已经按令牌、用户分组、模型限制和可用配置过滤。
```
curl "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

# {"object":"list","data":[{"id":"model-id","object":"model"}]}
```

### 当前参数与价格来源

#### 模型详情页
视频时长、分辨率、参考图、参考视频、Base64 与 multipart 字段，以对应模型章节为准。

#### 控制台价格
实际模型价格与分组倍率以控制台为准； 程序化获取见「账户信息 API」章节 ： GET /api/pricing （带账号令牌得专属价）。

### 机器可读接口（待更新）
以下机器可读接口用于让 Skill 与客户程序自助发现模型、参数与价格， 待更新 ；当前请以已开放的 /v1/models 为准。

#### 模型目录
按令牌返回显示名、类型、标签、能力和调用入口。

#### 参数 Schema
单模型参数、可选值、默认值与素材限制。

#### 客户可见价格
只按当前令牌返回有效计费单位与公开价格，不泄露内部渠道。

#### 按参数估价
时长、清晰度与素材组合影响价格时，复用真实账单逻辑估价。

### 本页

### 数据边界

---

# 账户与素材
来源：https://docs.oairegbox.cc/#sec-account-files

## 账户与素材
当前可查询令牌用量与限制；参考素材仍以模型协议为准。统一钱包余额与文件上传能力待更新。

### 当前令牌用量

#### Token Usage
读取当前令牌的额度、已用额度、模型限制和过期时间。
```
curl "$BASE_URL/api/usage/token/" \
  -H "Authorization: Bearer $API_KEY"

# data.total_available / data.total_used / data.model_limits / data.expires_at
```

### 当前参考素材方式

#### 公网 URL
仅在目标模型参数页明确支持时使用；链接必须可被目标模型访问。

#### Data URI
部分模型支持 data:image/...;base64,... ，其它模型可能忽略或拒绝。

#### 本地文件表单
仅使用目标模型公开的 multipart 字段，例如某些模型的 input_reference 。

#### 结果链接
把响应里的 video_url 或图片 URL 当作不透明地址使用，及时保存需要长期保留的产物。

### 账户与文件能力（待更新）
以下账户与文件能力 待更新 ，敬请关注。

#### 钱包余额
返回总额、预冻结、可用余额和实际币种；字段来自同一账本快照。

#### 文件上传
multipart 上传后返回客户安全、可被模型访问、具备过期策略的 URL。

#### 文件生命周期
文件元数据、删除、所有权检查、存储清理和可见 URL 过期时间。

#### 模型素材声明
由模型参数接口声明 URL、Base64、multipart 和限制，AI 不再猜测输入格式。

### 本页

### 重要边界

---

# 账户信息 API Account
来源：https://docs.oairegbox.cc/#sec-account-api

## 账户信息 API Account

### 两种鉴权粒度
| 粒度 | 鉴权头 | 能查到 |
| 令牌级 | Authorization: Bearer sk-你的令牌 | 这把令牌的 可见模型 + 这把令牌的 额度 |
| 账号级 | Authorization: Bearer 账号访问令牌 | 账号 已开启的全部模型 + 账号 总余额 + 账号 专属价格 |

### 账号凭据怎么拿（两选一）
| 方式 | 怎么获取 | 适用 |
| ① 账号访问令牌（推荐） | 登录后台 →「个人设置 / 个人中心」→ 生成系统访问令牌 ，复制保存（也可 GET /api/user/token 在登录态下签发； 重新签发会替换并使旧令牌失效 ） | 服务端脚本 / 长期自动化：长期有效、可随时重置、不受验证码 / 两步验证影响 |
| ② 账号密码换令牌 | POST /api/user/login ，body {"username":"...","password":"..."} → 取 data.access_token | 交互式 / 一次性：得到的是会话 JWT；账号开启两步验证时需再走 2FA。 ⚠️ 每次调用都会创建登录会话，勿用于反复自动化（见下） |
```
BASE_URL="https://api.oairegbox.cc"

# 方式②：账号密码换令牌（返回 data.access_token）
curl -sS -X POST "$BASE_URL/api/user/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"你的账号","password":"你的密码"}'
# => {"success":true,"data":{"access_token":"eyJhbGci...","user":{...}}}
```

### ① 令牌级：模型 + 额度（用 sk- ）
| 能力 | 接口 | 返回 |
| 令牌可见模型 | GET /v1/models | data[].id = 这把令牌可调用的模型（已按令牌 / 分组 / 模型限制过滤） |
| 令牌额度 | GET /api/usage/token/ | total_available / total_used / total_granted / unlimited_quota / model_limits / expires_at |
```
# 令牌可见模型
curl -sS "$BASE_URL/v1/models" -H "Authorization: Bearer sk-你的令牌"

# 令牌额度（total_* 为额度单位，¥ = 数值 / 500000；unlimited_quota=true 表示不限额）
curl -sS "$BASE_URL/api/usage/token/" -H "Authorization: Bearer sk-你的令牌"
# => {"data":{"total_available":..., "total_used":..., "unlimited_quota":false, "model_limits":[...], "expires_at":...}}
```

### ② 账号级：已开启模型 + 总余额（用账号令牌）
| 能力 | 接口 | 返回 |
| 账号已开启模型 | GET /api/user/models | data = 账号 所有可用分组里已启用 的模型名数组（去重）。可选 ?group=组名 筛某组、 ?group=auto 看智能分组 |
| 账号总余额 | GET /api/user/self | data.quota （剩余额度）、 data.used_quota （已用）、 data.group （账号分组） |
| 账号分组与倍率 | GET /api/user/self/groups | 账号可用分组及各组倍率 |
```
PAT="账号访问令牌或登录返回的 access_token"

# 账号已开启的全部模型（跨该账号所有可用分组、去重）
curl -sS "$BASE_URL/api/user/models" -H "Authorization: Bearer $PAT"
# => {"success":true,"data":["gemini-3-flash","claude-sonnet-4-6","flow-omni-1.1-flash", ...]}

# 账号总余额（¥ = data.quota / 500000）
curl -sS "$BASE_URL/api/user/self" -H "Authorization: Bearer $PAT"
# => {"success":true,"data":{"username":"...","group":"...","quota":2750000,"used_quota":123456, ...}}
#    quota=2750000 → ¥5.50
```

### 模型价格
GET /api/pricing 返回全部模型的价格目录。 匿名即可调用 （返回基准价）； 带账号令牌调用则反映该账号的分组倍率与专属折扣 ——要拿"这个账号真实到手价"请带账号令牌打。
| 字段 | 含义 |
| data[].model_name | 模型名 |
| data[].quota_type | 计费方式： 1 =按次固定价 / 0 =按量（token） |
| data[].model_price | 按次（ quota_type=1 ）时的 每次单价 （元，未乘分组倍率） |
| data[].model_ratio | 按量（ quota_type=0 ）时的倍率 |
| data[].enable_groups | 该模型所属分组 |
| data[].published_price | 有发布价档时的对客单价（更直观，优先用它） |
| group_ratio （顶层） | 各分组倍率 |
| usable_group （顶层） | 可用分组（账号鉴权时按账号过滤） |
```
# 匿名 = 基准价；带账号令牌 = 账号专属价（分组倍率 / 用户折扣已反映在 group_ratio）
curl -sS "$BASE_URL/api/pricing" -H "Authorization: Bearer $PAT"
```

### Python 完整示例（账号级：余额 + 模型 + 价格）
```
import requests

BASE = "https://api.oairegbox.cc"
PAT  = "账号访问令牌"          # 或用账号密码登录换 access_token（见上）
H = {"Authorization": f"Bearer {PAT}"}

# 账号总余额
me = requests.get(f"{BASE}/api/user/self", headers=H, timeout=30).json()["data"]
print("账号:", me["username"], "| 分组:", me["group"], "| 余额: ¥%.2f" % (me["quota"] / 500000))

# 账号已开启的全部模型
models = requests.get(f"{BASE}/api/user/models", headers=H, timeout=30).json()["data"]
print("已开启模型数:", len(models))

# 模型价格目录（账号专属价）
pr = requests.get(f"{BASE}/api/pricing", headers=H, timeout=30).json()
prices, group_ratio = pr["data"], pr.get("group_ratio", {})
for m in prices[:5]:
    if m["quota_type"] == 1:                       # 按次
        g = (m.get("enable_groups") or [""])[0]
        print(m["model_name"], "≈ ¥%.4f/次" % (m["model_price"] * group_ratio.get(g, 1)))
```

### 单位与注意事项
- 额度单位 ： 500000 = ¥1，即 人民币元 = quota / 500000 （本站直扣、汇率 1）。
- 只读、不计费 ：以上都是查询接口，不产生任何生成费用，可轮询（建议间隔 ≥ 数秒）。
- 两类凭据不互通 ： sk- 打不了 /api/user/* （401）；账号令牌也不用来打 /v1/* 生成。
- 令牌级 vs 账号级 ： sk- 可被设 model_limits 只放行部分模型、可单独限额；账号级看的是整个账号（跨所有分组）已启用模型与共享钱包。
- 价格以本站 / 控制台为准，接口数值供程序对账。

---

# Flow · Veo 3.1 视频
来源：https://docs.oairegbox.cc/#sec-flow

## Flow · Veo 3.1 视频
当前对外提供两个视频别名： flow-veo-3-1 （标准）与 flow-veo-3-1-fast （Fast）。两者均为异步任务，固定按次计费；失败任务不计费。
- 用 multipart/form-data 表单上传（含 Sora 风格的 input_reference / input_reference[0] ）；
- 用 image_url / first_image_url / first_image / last_image_url 字段（无论传 URL 还是 base64，均实测不生效）；
- 传图片 URL （系统要自行抓取，外部图床/带鉴权的链接大多抓不到 → 当没传处理）。所以一律转 base64 。

### 模型与价格
| 模型 | 能力 | 计费 | 价格 |
| flow-veo-3-1 | Veo 3.1 标准视频生成；文生、单图首帧、首尾帧字段可用 | 按次 | ¥0.46 / 次 |
| flow-veo-3-1-fast | Veo 3.1 Fast；请求结构与标准版相同，优先低延迟 | 按次 | ¥0.40 / 次 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （当前公开契约：JSON） |
| 轮询进度 | GET /v1/videos/{task_id} → status=completed 后取顶层 video_url （兼容 data[0].url ） |
| 下载成片 | 优先下载完成任务返回的 video_url ；媒体已就绪后也可使用 /v1/videos/{task_id}/content |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | gemini-flow-1 （Gemini flow） |
| 耗时 | 通常数十秒至数分钟；客户端应轮询，不要重复提交同一任务 |

### 核心参数
| 字段 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 只使用 flow-veo-3-1 或 flow-veo-3-1-fast |
| prompt | string | 是 | - | 画面、主体、动作、镜头和音频意图；建议写清主体数量与运动方向。无我方硬性长度上限（走 Veo 官方） |
| seconds | string / number | 否 | - | 推荐字符串如 "4" 。当前最低已验证 4 秒；实际成片可能被服务归一化为默认时长，以完成任务媒体信息为准 |
| duration | number / string | 否 | - | seconds 的兼容写法，例如 4 ；不要同时传两个不同值 |
| resolution | string | 否 | - | 兼容字段，建议改用官网式 video_resolution ； 当前仅 720p （⚠️ 官方已取消 1080p ，当前仅 720p） |
| size | string | 否 | - | 像素尺寸 1280x720 / 720x1280 ，或官网式纵横比 16:9 / 9:16 （须同时传 video_resolution ） |
| video_resolution | string | 否 | - | 官网式清晰度 仅 720p （官方已取消 1080p）。仅当 size 传纵横比时使用；网关转换为等价像素后发送 |
| aspect_ratio | string | 否 | - | 可传 16:9 / 9:16 作画幅意图；实测可提交，但服务可能归一化输出画幅 |
| ✅ image | string(base64) | 否 | - | 单图生视频主图 —— 经实测唯一生效的单图字段 。必须传 data:image/...;base64,.... （勿传图片 URL，系统抓不到会被忽略） |
| ✅ images | string[](base64) | 否 | - | 多图参考数组， 最多 3 张 ，每个元素为 data:image/...;base64,.... ；经实测生效 |
| ❌ image_url | string | 否 | - | 实测不生效 ：图片被静默忽略、退化为文生视频。请改用 image |
| ❌ first_image_url / first_image / last_image_url | string | 否 | - | 实测不生效 ；首尾帧当前无可用字段。单图用 image 、多图用 images |
| ❌ input_reference / multipart 文件 | - | 否 | - | 不支持 （Sora 格式）；用 multipart 上传或该字段，图片会被忽略、退化为文生视频 |

### 提交方式
当前唯一生效的图片传法： Content-Type: application/json + image / images 字段 + base64 （data URI） 。 不要用 multipart 文件上传，也不要传图片 URL （系统抓不到 → 图被忽略、退化为文生视频）。先把本地图片转成 data URI 再放进 image ：
```
IMAGE_B64=$(base64 < ./start.jpg | tr -d '\n')
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"flow-veo-3-1-fast\",
    \"prompt\": \"让图片中的主体自然运动\",
    \"seconds\": \"4\",
    \"resolution\": \"720p\",
    \"image\": \"data:image/jpeg;base64,$IMAGE_B64\"
  }"
```

### 示例请求
文生视频（最低已验证参数）
```
BASE_URL="https://newapi-2.oairegbox.cc"
TOKEN="sk-你的Flow令牌"

curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flow-veo-3-1",
    "prompt": "一只橘猫在窗边抬头，阳光缓慢移动，固定机位，电影感",
    "seconds": "4",
    "size": "16:9",
    "video_resolution": "720p"
  }'
```
Fast 版把 model 改为 flow-veo-3-1-fast 。竖屏把 size 改为 9:16 。
单图生视频（I2V）—— 用 image + base64（唯一生效）
```
IMG=$(base64 < ./start.jpg | tr -d '\n')
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"model\": \"flow-veo-3-1-fast\",
    \"prompt\": \"保持人物外观和服装一致，让人物自然回头并向镜头走来\",
    \"seconds\": \"4\", \"resolution\": \"720p\",
    \"image\": \"data:image/jpeg;base64,$IMG\"
  }"
```
多图参考（最多 3 张）—— 用 images + base64
```
A=$(base64 < ./character.jpg | tr -d '\n'); B=$(base64 < ./scene.jpg | tr -d '\n')
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"model\": \"flow-veo-3-1-fast\",
    \"prompt\": \"把图 1 的人物置于图 2 的场景，镜头缓慢推进\",
    \"seconds\": \"4\", \"resolution\": \"720p\",
    \"images\": [\"data:image/jpeg;base64,$A\", \"data:image/jpeg;base64,$B\"]
  }"
```

### 轮询取片
```
TASK_ID="task_xxx"
# shell 轮询示例（每 5 秒一次）
while :; do
  BODY=$(curl -fsS "$BASE_URL/v1/videos/$TASK_ID" -H "Authorization: Bearer $TOKEN") || exit 1
  STATUS=$(printf '%s' "$BODY" | jq -r '.status // "unknown"')
  echo "status=$STATUS"
  case "$STATUS" in
    completed|success|succeeded) break ;;
    failed|error) printf '%s\n' "$BODY" | jq .; exit 1 ;;
  esac
  sleep 5
done
VIDEO_URL=$(printf '%s' "$BODY" | jq -r '.video_url // .data[0].url // empty')
curl -fL "$VIDEO_URL" -o flow-veo-result.mp4
```
完成任务通常返回顶层 video_url ；客户端应同时兼容 data[0].url 。下载地址是临时地址，请及时转存。

### Python 完整请求
```
import time, requests
BASE = "https://newapi-2.oairegbox.cc"
H = {"Authorization": "Bearer sk-你的Flow令牌", "Content-Type": "application/json"}
# 提交
task = requests.post(f"{BASE}/v1/videos", headers=H, json={
    "model": "flow-veo-3-1-fast",
    "prompt": "一只橘猫在窗边抬头，阳光缓慢移动，固定机位，电影感",
    "seconds": "4", "size": "16:9", "video_resolution": "720p",
}).json()
tid = task["task_id"]
# 轮询
while True:
    r = requests.get(f"{BASE}/v1/videos/{tid}", headers=H).json()
    if r["status"] in ("completed", "success", "succeeded", "failed"):
        break
    time.sleep(5)
# 取 URL 下载（兼容顶层 video_url 与 data[0].url）
url = r.get("video_url") or (r.get("data") or [{}])[0].get("url")
open("flow-veo.mp4", "wb").write(requests.get(url).content)
```

### 注意事项
```
// 提交
{ "task_id": "task_xxx", "status": "queued", "progress": 0 }
// 轮询完成
{ "task_id": "task_xxx", "status": "completed", "progress": 100,
  "video_url": "https://sd.oaibox.xyz/d/dl/video/xxxx.mp4" }
// 失败
{ "task_id": "task_xxx", "status": "failed", "error": { "code": "...", "message": "..." } }
```
- queued / in_progress ：继续轮询，不要重复 POST。
- completed ：优先下载 video_url 。若立刻请求 /content 得 409 video_not_ready ，再查询一次任务后下载返回的 URL。
- failed ：本次任务不计费；修改提示词 / 图片 / 参数后再提交。
- 成片实际时长、宽高可能与请求的 seconds / resolution / aspect_ratio 不完全相同，以完成任务和媒体探测为准。

### 建议
- 当前最低已验收组合： seconds="4" + 720p 。成片可能被归一化（如 4 秒→8 秒），不是可依赖的固定规格。
- 图生视频只认 image （单图）/ images （多图，≤3 张）+ base64 ； image_url / first_image_url / input_reference /multipart 均实测不生效（图被忽略→变文生视频）。首尾帧当前不可用。
- 图片用 JPEG/PNG/WebP， 务必转成 base64 data URI （不要传 URL，系统要自行抓取，外链/带鉴权的大多抓不到）。
- 提示词写清"图 1 是谁 / 做什么""首帧到尾帧如何过渡"，比堆素材更稳定。
- 示例中的令牌 / URL / 任务 ID 均为占位符，勿把真实令牌提交到前端或公开仓库。

---

# Omni 视频生成
来源：https://docs.oairegbox.cc/#sec-omni

## Omni 视频生成
基于 Gemini Veo 的视频生成服务，支持文生视频、图生视频（最多 5 张参考图）、视频转视频（V2V，最多 2 个参考视频）。

### 模型与价格
| 模型 | 能力 | 计费 | 价格 |
| omni-fast | 文生视频 / 图生视频 | 按次 | ¥0.37/次 |
| omni-fast-v2v | 视频转视频（V2V） | 按次 | ¥0.52/次 |
| omni-fast-no-water | 文生/图生视频（无水印） | 按次 | ¥0.47/次 |
| omni-fast-v2v-no-water | V2V（无水印） | 按次 | ¥0.62/次 |
| omni-extend-20s | 视频续写（原片 + 约 8~10 秒） | 按次 | ¥0.52/次 |
| omni-extend-20s-no-water | 视频续写（无水印） | 按次 | ¥0.72/次 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （JSON 或 multipart） |
| 轮询进度 | GET /v1/videos/{task_id} |
| 下载成片 | GET /v1/videos/{task_id}/content 或返回的 data[0].url |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | gemini-fast |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 模型名，见上表 |
| prompt | string | 是 | - | 视频描述提示词（无我方硬性长度上限，走 Gemini 官方） |
| aspect_ratio | string | 否 | 16:9 | 画幅比例： 16:9 （横）、 9:16 （竖） |
| seconds / duration | string/int | 否 | 10 | 时长秒数（接收但当前 Gemini 固定输出约 10 秒） |
| image_url | string | 否 | - | 单张参考图（公网 URL 或 data:image Base64） |
| first_image_url | string | 否 | - | 首帧参考图 URL |
| last_image_url | string | 否 | - | 末帧参考图 URL |
| video / video_url | string | 否 | - | V2V 源视频 URL（≤8MB、≤1920x1080）。传 2 个视频时可用这两个字段各放一个 |
| videos | string[] | 否 | - | V2V 多源视频数组（最多 2 个，每个 ≤8MB） |
| images | string[] | 否 | - | 多参考图数组（最多 5 张，每张 ≤8MB） |

#### Multipart 提交（支持文件上传）
| 字段 | 说明 |
| input_reference / input_reference[] | 参考图文件上传（最多 5 张，每张 ≤8MB）。 input_reference[] 为浏览器画布 / Sora 兼容客户端的数组写法：单张=图生视频（首帧动画），多张=多参考图；两种写法均可 |
| input_video / input_video2 / videos[] | V2V 源视频文件上传（每个 ≤12MB，最多 2 个）。传 2 个视频用 input_video + input_video2 ；浏览器画布 / Sora 兼容客户端用数组写法 videos[] （同名重复），网关均可解析 |

### 示例：文生视频
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "雨夜霓虹街道，镜头缓慢推进，电影感光影",
    "aspect_ratio": "16:9"
  }'
```

### 让它照着念台词（只有文生视频做得到）
omni-fast 文生 / 图生视频会把你写的英文台词一字不差地念出来 ——把台词用引号写进提示词即可。8 个不同场景实测 逐字 8/8，按序命中率 1.00 。
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "A woman in a bright studio holds up a wireless earbud case to the camera. She speaks clearly to camera and says, \"This one lasts nine hours on a single charge.\" Bright commercial product-ad look.",
    "aspect_ratio": "16:9"
  }'
```
| 要照着念台词，选哪个模型 | 逐字命中 | 说明 |
| omni-fast 文生 / 图生视频 + 引号台词 | 8/8 | ✅ 想要精确台词就用它 |
| omni-extend-20s 续写 + 引号台词 | 0/6 | ❌ 会说话、会切题，但措辞自己编 |
| omni-extend-20s 续写 + 旁白句式 | 0/7 | ❌ 更糟，7 条里 3 条整段无声 |

### 示例：图生视频
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "保持人物一致，缓慢走动",
    "image_url": "https://your-cdn.com/photo.jpg",
    "aspect_ratio": "16:9"
  }'
```

### 示例：视频转视频（V2V）
```
# Multipart 文件上传
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=omni-fast-v2v" \
  -F "prompt=将画面风格转换为赛博朋克风" \
  -F "input_video=@source.mp4"
```

### 示例：双视频 V2V（2 个参考视频）
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast-v2v",
    "prompt": "融合两段素材，保持连续运动",
    "videos": ["https://your-cdn.com/a.mp4", "https://your-cdn.com/b.mp4"],
    "aspect_ratio": "16:9"
  }'
```
也可用 multipart/form-data 上传两个视频文件（字段 input_video + input_video2 ）：
```
# 双视频 · multipart 文件上传
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=omni-fast-v2v" \
  -F "prompt=第一个视频的人和第二个视频的人一起跳舞" \
  -F "input_video=@person1.mp4" \
  -F "input_video2=@person2.mp4"
```

### 视频续写（omni-extend-20s）
把你自己的一段短视频接长：上传 12 秒以内 的视频，返回「 原片 + 约 8~10 秒新画面 」。10 秒素材约得 18~20 秒成片，原片内容原样保留，只在后面自然接上。
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-extend-20s",
    "videos": ["https://your-cdn.com/clip.mp4"],
    "prompt": "continue naturally"
  }'
```
也可用 multipart/form-data 上传本地文件： -F "model=omni-extend-20s" -F "input_video=@clip.mp4"
| 要点 | 说明 |
| 续写提示词 | 越简单越好 ，推荐直接写 continue naturally 。在续写阶段详细描述画面元素（例如「把卡片转向镜头」）明显更容易触发内容审核而失败；创意请写在原片里。 |
| 画幅 | 不传 aspect_ratio 时 自动跟随原片 ，竖屏素材不会被裁切；传了则以你指定的为准。 |
| 素材时长 | 必须 ≤ 12 秒 ，超出会直接拒绝并提示， 不消耗额度 。 |
| 音频 | 加 "audio": "mute" 可得到 无声画面 ，便于后期配音。模型自带的声音不会延续原片台词，口播类建议后期配音。 |
| 必须带视频 | 纯文字请求会被拒绝——该模型只负责续写，不负责从零生成。 |
| 耗时与超时 | 中位约 3.5 分钟 ，90 分位约 7 分钟，最慢见过 12 分钟。 客户端轮询超时请设 ≥ 15 分钟 ，不要因为客户端超时就重新提交——先用原 task_id 继续轮询。 |
| 参考图字段别写错 | JSON 请求体里请用 images （数组，最多 5 张）。 input_reference 在 JSON 里 只能是单个字符串 ，写成数组会被网关直接挡下： invalid_json: cannot unmarshal array ... input_reference of type string 。要传多张就用 images 。 |
| video_action | 可选。用 omni-extend-20s 时网关默认就是续写；显式写 "video_action": "extend" 也可以，行为一致。 |
| 提示词能控什么 | 能控「做什么」，不能控「说什么」 。写动作、道具、运镜都有效（例如「旁边画一个红色圆圈」会真的画出来）。 写台词 不会被拒 （20 次实测通过 12 次，与不写台词无差别；另一组 16 次续写只有 1 次被拒），但 不会照着念 ——逐字命中 0/18 。它会说话、会切题、语种也对，只是措辞由模型自己编。 需要精确话术就出无声画面后期配音。 想让它讲某个话题，用 画面暗示 ：提示词里放「电池图标」，旁白就会讲续航。 |
| 加参考图的代价 | 参考图内容确实会进画面（ 提示词没提到它也会进 ），指定道具会被加进原场景而不是替换场景，实测有效 10/11 。 早期小样本曾观察到「带图更容易退化成等长重拍」，但 扩到各 20 次后没有复现 （带图 11/20、不带图 10/20）。 带图不额外计费，可以按需使用。 无论带不带图都要校验： 输出时长 < 原片时长 + 2 秒 即为 重拍 ——没加长但已扣额度，整体约 11%。 |
| 原片保真度 | 续写对原片是 逐帧原样保留 （首帧相关度实测 1.000 ），人物、商品、机位、光线全部锁死。 这是唯一能保住真人和商品细节的路径 。 |
| 不要用照片代替视频 | 用「一张照片 + 文生视频」做真人带货， 人物不会是照片里的那个人 ——实测首帧相关度只有 0.29~0.39 ，商品五金件也会被重画。真人主播 / 商品细节必须严格一致时， 请提供真实拍摄的短视频走续写 ，不要走图生视频。 |
| 口播台词 | 语种可以指定，内容不可以。 提示词里写明英语 / 中文 / 粤语都能生效，实测粤语链式 8 轮全程保持粤语。 但续写不会逐字念你写的台词 ——它会说话、会切题、语种也对，措辞却是自己编的。单变量实测 逐字 0/6 （并入更早的 12 条共 0/18 ），按序命中率仅 0.25。 ⚠️ 千万不要写成旁白句式 （ a voice over says: "..." ）：实测逐字 0/7 ，且 7 条里有 3 条整段完全无声 ，比直接写引号台词更糟。 需要精确话术：出无声画面后期配音。 要「照着念」请改用 omni-fast 文生视频，见下方对照。 |
| 收到 content_policy 怎么办 | 不要重试，换素材（换题材）。 先说清楚一件事： 这个错误码的名字有误导性 。我们抓了 168 次失败逐条看过， 真正被内容审核判掉的只有 1 次 ；绝大多数是 这次请求没被派给视频模型 ——请求在更前面一层就被挡下了，跟你这条文件"干不干净"基本无关。所以画面完全正常的素材照样可能收到它。 后果是： 任何针对文件本身的补救都没用 。专项对照实测——换编码重传 1/10 ，什么都不做 2/15 ， 重试比不重试还差 （多烧 10~15 分钟）。改提示词、改码率、改分辨率同理。 它占全部失败的 88% 。拒绝 不生成视频、不扣额度 。 唯一有效的做法是换题材 ——见下面的「题材成功率」表，幼儿类 0/14、产品广告 14/14，差距就在这里。 |
| 参考图控制 | 可同时传 images （最多 5 张，data URI 或公网 URL）来控制续写段出现的商品或元素。 人设、画风、场景由原片锁定，商品由参考图决定 ——带货场景常用。参考图建议用商品图 / 白底图， 尽量不要带人 。加图不额外计费。 |
示例：续写时用一张商品图控制画面中出现的商品——
```
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-extend-20s",
    "videos": ["https://your-cdn.com/host.mp4"],
    "images": ["https://your-cdn.com/product.jpg"],
    "prompt": "continue naturally"
  }'
```

### 用 URL 传参考视频和参考图
不想传 base64、也不想走 multipart，可以 直接给公网 URL ，视频和图片都支持。服务端会替你下载（经代理，不暴露你我的 IP），你只要保证链接能被匿名 GET 到。
```
# 参考视频 + 参考图,全部用 URL
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-extend-20s",
    "prompt": "continue naturally",
    "videos": ["https://your-cdn.com/clip.mp4"],
    "images": ["https://your-cdn.com/product.jpg"]
  }'
```

#### 字段对照
| 要传的东西 | 推荐字段 | 也接受 | 上限 |
| 参考视频 | videos （数组） | video_url / video / input_video （各放一个） | 最多 2 个，每个 ≤12MB、≤12 秒、≤1920×1080 |
| 参考图 | images （数组） | image_url / first_image_url / last_image_url | 最多 5 张，每张 ≤12MB |
同一个字段里 URL 和 data:...;base64, 可以混着写，服务端按前缀自己分辨。 multipart 也能混用 ：视频用 -F "input_video=@clip.mp4" 上传文件，图片同时用 -F "image_url=https://..." 给链接。

#### URL 必须满足
| 要求 | 说明 |
| 匿名可下载 | 服务端下载时 不会带你的任何鉴权头 。需要签名/登录才能访问的私有链接一律取不到，请用预签名直链（presigned URL）或公开对象。 |
| 直链，返回 200 | 要指向文件本身，不是网盘的分享页 / 播放页。302 跳转可以，会自动跟随。 |
| 时效要够 | 预签名 URL 的有效期建议留 30 分钟以上 ：任务排队 + 生成的中位耗时约 3.5 分钟，最慢见过 12 分钟。 |
| Content-Type | 不强制。服务端识别不了时按 video/mp4 / image/jpeg 兜底。 |

### 题材决定成败（实测 140 次）
我们用 7 组不同的提示词写法 × 20 条不同题材的源片各跑了一遍。结论很干脆： 提示词怎么写几乎不影响成功率，源片是什么题材才是决定性因素。
七组提示词的成功率全部落在 10~13 / 20，差异在噪声范围内：
| 提示词写法 | 成功 | 提示词写法 | 成功 |
| 4 词极短（ continue naturally ） | 13/20 | 中文提示词 | 11/20 |
| 25 词中等 | 10/20 | 指定台词 | 12/20 |
| 110 词长提示 | 12/20 | 带参考图 / 带分镜图 | 11/20 / 13/20 |
所以直接用最短的 continue naturally 就行，把精力花在选素材上。
| ✅ 高成功率题材 | 实测 | ❌ 高风险题材 | 实测 |
| 产品广告 | 14/14 | 幼儿 / 亲子 | 0/14 |
| 产品演示 / 教程 | 13/14 | 纯动作、无对白 | 1/14 |
| 口播带货 | 15/21 | 情绪冲突剧情 | 9/28 |
| 动物 / 自然 | 12/14 |  |  |
| 风景 / 空镜 | 11/14 |  |  |

#### 不同失败的处理方式是相反的
| 现象 | 怎么办 |
| 重拍 （输出时长 < 原片 + 2 秒） | 原地重试 ，最多 3 次，多数第 2 次就过 |
| video_route_misroute | 原地重试 ，偶发 |
| content_policy | 不要重试，换素材 （素材级判定，重试无效） |

### 做 20 秒以上：尾部窗口链式
失败率是跟着 你喂进去的参考视频长度 走的，不是跟着输出长度走的：
| 参考视频长度 | 10 秒 | 20 秒 | 28 秒 |
| 成功 | 2/2 | 2/4 | 0/2 |
所以想接到 30 秒、60 秒， 千万不要把整条成片喂回去 ，而是每轮只截最后 10 秒：
```
第 1 轮：一段 10 秒素材                              → 成片 10 秒
第 2 轮：截成片最后 10 秒 → 续写 → 返回 20 秒
        只保留新增的后 10 秒，接到片尾                → 成片 20 秒
第 3 轮：再截最后 10 秒 → 续写 → 只留新增的后半段     → 成片 30 秒
...依此类推
```
这样喂进去的参考永远停在 10 秒，一直待在高成功率区间。实测这样连做 8 轮做到 79 秒 ，全程画幅、人物、旁白语种都保持一致。

### 多角色内容：身份要在每一段里重申
续写对 原片 是逐帧保真的，但如果你是用「参考图 + 图生视频」起头再链式接长，要注意： 参考图锁得住「长什么样」（构图、服装、场景、光线），锁不住「是谁」。 实测同一套参考图，第二段里的白人角色会被重新生成成亚洲面孔。
做法： 把人种、发色、年龄、体型、服装写进每一段的提示词，逐字重复，不要用「她」「那个女人」这类指代。

### 轮询取片
```
curl https://YOUR_BASE/v1/videos/{task_id} \
  -H "Authorization: Bearer sk-xxx"

# 完成后（优先读顶层 video_url，兼容 data[0].url；均为完整下载直链）:
# {"status":"completed",
#  "video_url":"https://download.oaibox.xyz/v1/videos/vid-xxxx/content",
#  "data":[{"url":"https://download.oaibox.xyz/v1/videos/vid-xxxx/content"}]}
```

---

# 反重力 Antigravity（Claude + Gemini 图文）
来源：https://docs.oairegbox.cc/#sec-anti

## 反重力 Antigravity（Claude + Gemini 图文）
提供两大反重力独立分组： gemini-anti-ultra （展示名 Gemini Antigravity Ultra ，反重力 Ultra 独立号池专线，倍率 1.0 ，已纳入 auto 自动分组，承载旗舰模型 gemini-4-argon ）与 gemini-anti （0.28x 特惠分组，提供 Claude Opus / Sonnet 4.6 + Gemini 文本 + 原生 4K 出图 ）。支持标准 OpenAI 兼容接口与 Gemini 原生接口，支持 图文理解、Reasoning 思维链、流式输出与 Function Calling 工具调用 。

### 模型与价格

#### 1. gemini-anti-ultra 分组（Gemini Antigravity Ultra · 反重力 Ultra 独立专线，倍率 1.0）
| 分组代号 | 分组展示名 | 模型名 | 分组倍率 | 输入单价 | 输出单价 | 缓存单价 | 定位说明 |
| gemini-anti-ultra | Gemini Antigravity Ultra | gemini-4-argon | 1.0 | ¥2/M （¥2.00/M） | ¥10/M （¥10.00/M） | ¥0.2/M | 反重力 Ultra 独立号池专线（官方基准 2/10 无折扣，支持工具调用，高稳主力） |
| gemini-fast | Gemini Fast | gemini-4-argon-app | 1.0 | ¥0.56/M | ¥2.8/M | ¥0.056/M | 高性价比快速通道（纯对话/图文理解，不支持工具调用；详见「Gemini 高速文本」章节） |

#### 2. gemini-anti 分组（0.28x 特惠）与反重力全系模型一览
| 模型 | 类型 | 价格（¥ 与 $ 按 1:1） |
| gemini-4-argon | Gemini 4 旗舰·图文/思维链/工具调用（分组 gemini-anti-ultra ，倍率 1.0） | 入 ¥2/M · 出 ¥10/M · 缓存 ¥0.2/M |
| claude-opus-4-6-thinking | Claude 顶配·带思考 | 入 $3.2/M · 出 $16/M · 缓存 $0.32 |
| claude-sonnet-4-6 | Claude 均衡 | 入 $2.4/M · 出 $12/M · 缓存 $0.24 |
| gemini-3.1-pro-low | Gemini Pro 文本 | 入 $0.48/M · 出 $2.88/M |
| gemini-3-flash | Gemini Flash 文本 | 入 $0.4/M · 出 $1.6/M |
| gemini-3.6-flash-high | Gemini Flash 高质 | 入 $0.24/M · 出 $2/M · 缓存 $0.06 |
| gemini-3.1-flash-image-4k | 原生 4K 出图（5632×3072） | 按次 ¥0.112/张 |

### 接口信息
| 项 | 说明 |
| 请求 | OpenAI 兼容： POST https://api.oairegbox.cc/v1/chat/completions Gemini 原生： POST https://api.oairegbox.cc/v1beta/models/gemini-4-argon:generateContent / :streamGenerateContent |
| Base URL | https://api.oairegbox.cc |
| 令牌分组 | gemini-anti-ultra （ gemini-4-argon 独立专线，倍率 1.0 ，已纳入 auto 链） gemini-anti （Claude / Gemini 0.28x 特惠分组） |
| 支持能力 | 图文理解、Reasoning 思维链、流式输出（ "stream": true ）、Function Calling 工具调用（ tools / tool_choice ） |
| Function Call | 支持（ tools / tool_choice ） |
| 流式 | 支持（ "stream": true 或 :streamGenerateContent ） |

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | 见上表；Claude / Gemini / 4K 出图切换 model 即可 |
| messages | array | 是 | OpenAI 标准对话消息 |
| stream | bool | 否 | true 开启流式 |
| tools / tool_choice | array / string | 否 | Function Call（Claude / Gemini 均支持） |
| temperature / max_tokens 等 | - | 否 | OpenAI 标准采样参数 |

### 提交方式
文本对话、Function Call、4K 出图 全部走同一端点 POST /v1/chat/completions ，切换 model 即可。4K 出图（ gemini-3.1-flash-image-4k ）的图片在响应 choices[0].message.images[].image_url.url （ data:image/jpeg;base64 ）返回。

### 示例：Claude 对话
```
curl https://newapi.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"用一句话解释量子纠缠"}]
  }'
```

### 示例：4K 出图
图像通过对话接口返回，结果在 choices[0].message.images[].image_url.url （ data:image/jpeg;base64 ）。强制输出 4K（5632×3072）。
```
curl https://newapi.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-4k",
    "messages": [{"role":"user","content":"一只戴宇航头盔的柴犬，电影级布光"}]
  }'
```

### 示例：Function Call
```
curl https://newapi.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"北京天气如何"}],
    "tools": [{"type":"function","function":{
      "name":"get_weather",
      "parameters":{"type":"object","properties":{"city":{"type":"string"}}}
    }}]
  }'
```

### 轮询取片
本分组均为 同步对话接口 （含 4K 出图，图片直接在对话响应里返回）， 无需轮询 task_id。

### Python 完整请求
```
from openai import OpenAI

client = OpenAI(api_key="sk-xxx", base_url="https://newapi.oairegbox.cc/v1")
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

### 示例： gemini-4-argon （OpenAI 兼容与 Gemini 原生）
```
# 1. OpenAI 兼容格式（POST /v1/chat/completions）
curl https://api.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "messages": [{"role":"user","content":"分析量子纠缠在量子通信中的核心作用"}],
    "stream": false
  }'

# 2. Gemini 原生格式（POST /v1beta/models/gemini-4-argon:generateContent）
curl https://api.oairegbox.cc/v1beta/models/gemini-4-argon:generateContent \
  -H "x-goog-api-key: sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "分析量子纠缠在量子通信中的核心作用"}]}]
  }'
```

### 注意事项
- 调用反重力 Ultra 专线的 gemini-4-argon 需使用 gemini-anti-ultra 分组或 auto 自动分组令牌（入 ¥2/M · 出 ¥10/M · 缓存 ¥0.2/M，倍率 1.0）；调用其余 0.28x 特惠模型需在 gemini-anti 分组下
- gemini-3.1-flash-image-4k 固定输出 4K，按次计费（¥0.112/张），失败不计费
- Claude 与 Gemini 均走同一 /v1/chat/completions ，切换 model 即可； gemini-4-argon 同时支持 Gemini 原生端点 /v1beta/models/gemini-4-argon:generateContent 与 :streamGenerateContent

### 建议
- Claude 顶配 用带思考版 claude-opus-4-6-thinking ；日常均衡用 claude-sonnet-4-6 。
- 要 4K 出图 用 gemini-3.1-flash-image-4k （固定 5632×3072，按次 ¥0.112/张），图在 message.images[].image_url.url 取。
- Claude 与 Gemini 同端点 ，用 OpenAI SDK 只换 model 即可无缝切换；支持 tools function call 与 stream 。

---

# Google Vertex AI & AI Studio（官方原生模型）
来源：https://docs.oairegbox.cc/#sec-official

## Google Vertex AI & AI Studio（官方原生模型）
直连 Google Vertex AI 企业级通道（主力分组 gemini-vertex ，倍率 1.8 ）与 Google AI Studio（分组 gemini-official ，倍率 1.6 ），模型名与 Google 官方完全一致。文本与原生图像生成同时支持 OpenAI 兼容端点 POST /v1/chat/completions 与 Gemini 原生端点 POST /v1beta/models/{model}:generateContent 。

### 一、 gemini-vertex 分组模型与价格（Google Vertex AI · 倍率 1.8）
当前主力官方原生分组为 gemini-vertex （展示名 Gemini Vertex ），基于 Google 官方标准单价 × 分组倍率 1.8 计费（人民币 ¥ 与美元 $ 按 1:1）：

#### 1. 原生图像生成与图文对话模型（按 token）
| 模型 | 定位说明 | 计费 | 1.0× 官方基准 | gemini-vertex （1.8×）实际单价 | 单张图片预估成本 |
| gemini-3-pro-image | Nano Banana Pro 旗舰原生多模态生图 / 图文编辑 | 按 token | 入 ¥2/M · 出 ¥120/M · 缓存 ¥0.2/M | 入 ¥3.6/M · 出 ¥216/M · 缓存 ¥0.36/M | 约 ¥0.27 ~ ¥0.29 / 张 （输出 ~1,240 tokens） |
| gemini-3.1-flash-image | Nano Banana 2 轻量高速原生生图 | 按 token | 入 ¥0.5/M · 出 ¥60/M · 缓存 ¥0.05/M | 入 ¥0.9/M · 出 ¥108/M · 缓存 ¥0.09/M | 约 ¥0.13 ~ ¥0.15 / 张 |
| gemini-2.5-flash-image | Gemini 2.5 Flash 原生多模态生图 | 按 token | 入 ¥0.3/M · 出 ¥30/M · 缓存 ¥0.03/M | 入 ¥0.54/M · 出 ¥54/M · 缓存 ¥0.054/M | 约 ¥0.07 ~ ¥0.08 / 张 |

#### 2. 文本与多模态推理模型（按 token）
| 模型 | 1.0× 官方基准 | gemini-vertex （1.8×）实际单价 |
| gemini-4-argon | 入 ¥2/M · 出 ¥10/M · 缓存 ¥0.2/M | 入 ¥3.6/M · 出 ¥18/M · 缓存 ¥0.36/M |
| gemini-3-pro-preview | 入 ¥2/M · 出 ¥12/M · 缓存 ¥0.2/M | 入 ¥3.6/M · 出 ¥21.6/M · 缓存 ¥0.36/M |
| gemini-3.5-flash | 入 ¥0.75/M · 出 ¥3.75/M · 缓存 ¥0.075/M | 入 ¥1.35/M · 出 ¥6.75/M · 缓存 ¥0.135/M |
| gemini-3-flash-preview | 入 ¥0.5/M · 出 ¥3/M · 缓存 ¥0.05/M | 入 ¥0.9/M · 出 ¥5.4/M · 缓存 ¥0.09/M |
| gemini-2.5-pro | 入 ¥1.25/M · 出 ¥10/M · 缓存 ¥0.125/M | 入 ¥2.25/M · 出 ¥18/M · 缓存 ¥0.225/M |
| gemini-2.5-flash | 入 ¥0.3/M · 出 ¥2.5/M · 缓存 ¥0.03/M | 入 ¥0.54/M · 出 ¥4.5/M · 缓存 ¥0.054/M |

### 二、 gemini-official 分组参考价格（Google AI Studio · 倍率 1.6）

#### 文本模型（按 token）
| 模型 | 价格 |
| gemini-2.5-pro | 入 $2/M · 出 $16/M |
| gemini-2.5-flash | 入 $0.48/M · 出 $4/M |
| gemini-3.1-pro-preview | 入 $3.2/M · 出 $19.2/M · 缓存 $0.32 |
| gemini-3.1-pro-preview-customtools | 入 $3.2/M · 出 $19.2/M |
| gemini-pro-latest | 入 $3.2/M · 出 $19.2/M |
| gemini-3.5-flash | 入 $2.4/M · 出 $14.4/M |
| gemini-flash-latest | 入 $2.4/M · 出 $12/M |
| gemini-3-flash-preview | 入 $0.8/M · 出 $4.8/M · 缓存 $0.08 |
| gemini-3.1-flash-lite / gemini-3.1-flash-lite-preview | 入 $0.4/M · 出 $2.4/M |
| gemini-flash-lite-latest | 入 $0.48/M · 出 $4/M |
| gemini-robotics-er-1.6-preview | 入 $1.6/M · 出 $8/M |

#### 图像模型
| 模型 | 计费 | 价格 |
| gemini-3-pro-image / -preview | 按 token | gemini-vertex （1.8×）：入 ¥3.6/M · 出 ¥216/M（约 ¥0.27~0.29/张）； gemini-official （1.6×）：入 $3.2/M · 出 $192/M |
| gemini-3.1-flash-image | 按 token | gemini-vertex （1.8×）：入 ¥0.9/M · 出 ¥108/M； gemini-official （1.6×）：入 $0.8/M · 出 $96/M |
| gemini-3.1-flash-image-preview | 按 token | 入 $0.4/M · 出 $96/M |
| gemini-3.1-flash-lite-image | 按 token | 入 $0.4/M · 出 $48/M |
| gemini-2.5-flash-image | 按 token | gemini-vertex （1.8×）：入 ¥0.54/M · 出 ¥54/M； gemini-official （1.6×）：入 $0.48/M · 出 $48/M |
| gemini-3-pro-image-preview-1k | 按次 | ¥0.214/张 |
| gemini-3-pro-image-2k | 按次 | ¥0.214/张 |
| gemini-3-pro-image-4k | 按次 | ¥0.384/张 |

#### 音乐（异步按次）
| 模型 | 类型 | 价格 |
| lyria-3-pro-preview | 音乐 | 按次 ¥0.128/次 |
| lyria-3-clip-preview | 音乐·短 | 按次 ¥0.064/次 |

### 接口信息
| 项 | 说明 |
| 文本 / 图像（OpenAI 兼容） | POST /v1/chat/completions （图片以 Markdown data:image/png;base64,... 在 choices[0].message.content 返回） |
| 文本 / 图像（Gemini 原生） | POST /v1beta/models/{model}:generateContent （图片以 candidates[0].content.parts[].inlineData 返回） |
| 音乐 | 异步任务 POST /v1/videos 提交 → 轮询取片（同「Omni 视频生成」板块） |
| Base URL | https://api.oairegbox.cc （备用 https://newapi.oairegbox.cc ） |
| 令牌分组 | gemini-vertex （主力 Google Vertex AI 通道，倍率 1.8 ） / gemini-official （倍率 1.6 ） |

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | 与 Google 官方一致，如 gemini-3-pro-image 、 gemini-2.5-pro 等 |
| messages | array | OpenAI 格式 | OpenAI 标准对话消息（图像模型同样走对话，支持传入图片做图文编辑，生成图在响应返回） |
| contents | array | Gemini 原生格式 | /v1beta/models/{model}:generateContent 标准请求体 |
| prompt | string | 音乐 | lyria 音乐任务的描述（异步 /v1/videos ） |
| stream / tools 等 | - | 否 | OpenAI 标准参数（文本 / 图像走 chat） |

### 提交方式
| 类型 | 端点 | 结果 |
| 文本 / 图像（OpenAI 格式） | POST /v1/chat/completions （同步） | 文本与 Base64 图片在 choices[0].message.content 返回 |
| 文本 / 图像（Gemini 原生） | POST /v1beta/models/{model}:generateContent （同步） | 文本在 parts[].text ，Base64 图片在 parts[].inlineData.data 返回 |
| 音乐（lyria） | POST /v1/videos （异步） | 提交拿 task_id → 轮询取片 |

### 示例：官方文本
```
curl https://api.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"你好"}]
  }'
```

### 示例： gemini-3-pro-image 官方原生出图（OpenAI 兼容与 Gemini 原生双格式）
```
# 方式 1：OpenAI Chat 兼容格式（POST /v1/chat/completions）
curl https://api.oairegbox.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "messages": [{"role":"user","content":"生成一张赛博朋克风格的城市夜景海报，霓虹灯倒映在雨夜街道"}],
    "stream": false
  }'

# 方式 2：Google Gemini 原生格式（POST /v1beta/models/gemini-3-pro-image:generateContent）
curl "https://api.oairegbox.cc/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"生成一张赛博朋克风格的城市夜景海报，霓虹灯倒映在雨夜街道"}]}]
  }'
```

### 示例：官方音乐（lyria，异步任务）
```
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-pro-preview",
    "prompt": "轻快的钢琴爵士，适合咖啡馆"
  }'
# 轮询取片同上（GET /v1/videos/{task_id}）
```

### 轮询取片
文本 / 图像为 同步 接口，直接返回、无需轮询。 音乐（lyria）为异步任务 ： POST /v1/videos 提交拿 task_id ，再 GET /v1/videos/{task_id} 轮询到 completed 取结果（同「Omni 视频生成」板块）。

### Python 完整请求（含 gemini-3-pro-image 出图解码）
```
import base64, re
from openai import OpenAI

client = OpenAI(api_key="sk-xxx", base_url="https://api.oairegbox.cc/v1")

# 1. 官方文本（gemini-vertex 分组）
resp = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

# 2. gemini-3-pro-image 原生出图并保存 PNG
img_resp = client.chat.completions.create(
    model="gemini-3-pro-image",
    messages=[{"role": "user", "content": "一只戴着宇航头盔的橘猫，电影级布光"}],
)
content = img_resp.choices[0].message.content or ""
m = re.search(r"data:image/[^;]+;base64,([A-Za-z0-9+/=\s]+)", content)
if m:
    with open("gemini-3-pro-image.png", "wb") as f:
        f.write(base64.b64decode(re.sub(r"\s+", "", m.group(1))))
    print("Saved gemini-3-pro-image.png")
```

### 注意事项
- 调用 Vertex 原生模型（含 gemini-3-pro-image 、 gemini-3.1-flash-image 、 gemini-2.5-flash-image 等）请将令牌分组设为 gemini-vertex （倍率 1.8 ）
- gemini-3-pro-image 等原生图像模型走 /v1/chat/completions 或 /v1beta/models/{model}:generateContent ， 不走 /v1/images/generations
- 音乐（lyria）为异步按次任务，提交与轮询方式见「Omni 视频生成」板块

### 建议
- 要 Google Vertex 原生模型与 gemini-3-pro-image ：使用 gemini-vertex 分组令牌（倍率 1.8， gemini-3-pro-image 单张图约 ¥0.27~¥0.29）。
- 需要固定按次 /v1/images/generations 接口 ：可使用 gemini-fast 分组的 gemini-image （¥0.11/张）或 gemini-image-pro （¥0.12/张），详见「Gemini 图像生成」章节。
- 音乐 lyria 走异步 /v1/videos ，提交后轮询取片，别用 chat 端点。

---

# Veo-Clean 去水印
来源：https://docs.oairegbox.cc/#sec-veo-clean

## Veo-Clean 去水印
上传带水印的视频，系统自动去除水印后返回去水印成片。异步任务，流程与视频生成一致。

### 模型与价格
| 模型 | 能力 | 计费 | 价格 |
| veo-clean | 视频去水印 | 按秒 | ¥0.10/秒 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （ 仅 multipart ，需上传文件） |
| 轮询进度 | GET /v1/videos/{task_id} |
| 下载成片 | GET /v1/videos/{task_id}/content 或返回的 data[0].url |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | gemini-fast |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 固定 veo-clean |
| input_video | file | 是 | - | 带水印视频文件， ≤20MB ，必须 multipart 上传 |
| prompt | string | 是 | - | 去水印指令，通常填 remove watermark ；网关要求必填，缺省会返回 400 prompt is required |

### 提交方式
仅支持 multipart/form-data （必须上传视频文件，不支持 JSON / URL 传视频）。字段 input_video 放本地文件。

### 示例请求
```
# Multipart 上传去水印
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=veo-clean" \
  -F "prompt=remove watermark" \
  -F "input_video=@watermarked.mp4"
```

### 轮询取片
```
curl https://YOUR_BASE/v1/videos/{task_id} \
  -H "Authorization: Bearer sk-xxx"
# 完成后:
# {"status":"completed","data":[{"url":"/v1/videos/{task_id}/content"}]}
```

### Python 完整请求
```
import time, requests
BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-xxx"}
# 提交(multipart)
with open("watermarked.mp4", "rb") as f:
    task = requests.post(f"{BASE}/videos", headers=H,
        data={"model": "veo-clean", "prompt": "remove watermark"}, files={"input_video": f}).json()
tid = task["task_id"]
# 轮询
while True:
    r = requests.get(f"{BASE}/videos/{tid}", headers=H).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(3)
# 下载
url = r["data"][0]["url"]
if url.startswith("/"):
    url = "https://YOUR_BASE" + url
open("clean.mp4", "wb").write(requests.get(url, headers=H).content)
```

### 注意事项
- 仅支持 multipart/form-data 提交（需上传视频文件）。
- 视频文件大小限制 20MB 。
- 处理时间通常 20–60 秒（取决于视频长度），清洗前可能多一个 processing 阶段。
- 不涉及 Gemini 视频生成，不消耗生成配额；失败不计费。

### 建议
- 源视频尽量 ≤20MB、时长越短处理越快。
- 清晰源视频去水印效果更好；严重压缩 / 低清源可能残留痕迹。

---

# Adobe Firefly · Veo 3.1
来源：https://docs.oairegbox.cc/#sec-firefly-veo

## Adobe Firefly · Veo 3.1
Adobe Firefly 视频生成现已提供 Veo 3.1 标准版、Veo 3.1 Fast（静音档， 无音频 ）与 Veo 3.1 Fast Direct（含音频）。两者均使用 OpenAI 兼容的异步视频接口：提交任务后轮询，完成时从响应中的 video_url 获取成片。

### 模型与价格
| 模型 | 说明 | 当前验收规格 |
| firefly-veo-3.1 | Veo 3.1 标准版 · 含音频 | 文/图生视频，4 秒、6 秒、8 秒 |
| firefly-veo-3.1-fast | Veo 3.1 Fast，优先低延迟 · 无音频（静音输出） | 文/图生视频，4 秒、6 秒、8 秒 |
| firefly-veo-3.1-fast-direct | Veo 3.1 Fast 高质档 · 含音频 （同为 Fast，仅积分档可用） | 文/图生视频，4 秒、6 秒、8 秒 |
实际计费、模型可见性和可用额度以控制台模型列表及你的 API 令牌权限为准。

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc |
| 提交任务 | POST /v1/videos |
| 查询任务 | GET /v1/videos/{task_id} |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 任务模式 | 异步；提交成功仅表示任务已入队 |
| 成片交付 | 任务 status 为 completed 后，读取顶层 video_url |

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | 使用上表中的一个模型名 |
| prompt | string | 是 | 视频画面、主体、动作、镜头和风格描述 |
| seconds | string | 是 | 目标时长（秒），可选 "4" 、 "6" 、 "8" ，三者均支持 |
| video_seconds | string | 否 | 无需传；只传 seconds 即可 |
| size | string | 是 | 两种传法，任选其一： ① 像素式 宽x高 ： "1280x720" （横 720p）、 "720x1280" （竖 720p）、 "1920x1080" （横 1080p）、 "1080x1920" （竖 1080p）——画幅与清晰度自动识别， video_resolution 无需传。 ② 官网式 纵横比 "16:9" （横）/ "9:16" （竖）——此时 必须同时传 video_resolution ，否则报错。 |
| video_resolution | string | 条件必填 | size 传 像素 时：无需传（清晰度由像素决定）。 size 传 纵横比 （ 16:9 / 9:16 ）时： 必填 ，取 "720p" 或 "1080p" ，否则报“size 为纵横比(16:9/9:16)时必须同时提供 video_resolution”。 |
| input_reference | string / 文件 | 否 | 图生视频用 ：参考图（首帧）。可传图片 URL、base64（ data:image/...;base64, ）或 multipart 文件（ @frame.jpg ）；不传即为文生视频。带此参数时整个请求改用 multipart 表单提交（见下方“图生视频”示例） |

#### size 取值与输出
| size （传这个） | 画幅 | 清晰度 |
| "1280x720" | 横版 16:9 | 720p |
| "720x1280" | 竖版 9:16 | 720p |
| "1920x1080" | 横版 16:9 | 1080p |
| "1080x1920" | 竖版 9:16 | 1080p |

#### 官网式取值（ size 纵横比 + video_resolution ）
| size | video_resolution | 输出 |
| "16:9" | "720p" | 横版 1280x720 |
| "16:9" | "1080p" | 横版 1920x1080 |
| "9:16" | "720p" | 竖版 720x1280 |
| "9:16" | "1080p" | 竖版 1080x1920 |

### 提交方式
| 模式 | Content-Type | 参考素材 |
| 文生视频（T2V） | application/json | 无 |
| 图生 / 首尾帧 / 多参考图 | multipart/form-data （ -F ） | 带 input_reference / first_frame + last_frame / reference_images 时改用表单 |

### 示例：提交 6 秒 Fast 视频
```
BASE_URL="https://newapi-2.oairegbox.cc"
TOKEN="sk-xxx"

curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-veo-3.1-fast",
    "prompt": "日出时一盏彩色纸灯笼缓缓飘过安静的湖面，水面泛起微光，电影感镜头，无文字无标志。",
    "seconds": "6",
    "size": "1280x720"
  }'
```

### 示例：官网式参数（纵横比 + 分辨率）
与像素式输出完全一致，区别只是把画幅和清晰度拆成 size （纵横比）+ video_resolution 两栏，对齐 Adobe 官网 UI。 size 传纵横比时 video_resolution 必填 。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-veo-3.1-fast",
    "prompt": "日出时一盏彩色纸灯笼缓缓飘过安静的湖面，水面泛起微光，电影感镜头，无文字无标志。",
    "seconds": "6",
    "size": "16:9",
    "video_resolution": "720p"
  }'
```

### 示例：图生视频（带参考图 input_reference）
在文生的基础上，用 multipart 表单 额外带一张参考图作为首帧，其余参数（ seconds 、 size ）一致。 input_reference 支持 本地文件 、 图片 URL 或 base64 三种传法。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-veo-3.1' \
  -F 'prompt=让画面里的主体自然动起来，镜头缓慢向前推进，保持构图。' \
  -F 'seconds=6' \
  -F 'size=1280x720' \
  -F 'input_reference=@frame.jpg;type=image/jpeg'
```

### 首尾帧（First / Last Frame）
用 first_frame （起始帧）和 last_frame （结束帧）两张图，引导 Veo 从首帧画面过渡到尾帧画面。两个字段都支持 图片 URL 、 base64 （ data:image/...;base64, ）或 multipart 文件 。 只传 first_frame 等同于用首帧做图生视频 （与上面的 input_reference 首帧一致）。 首尾帧模式与下方“多参考图”模式互斥，不能同一请求混用 （Adobe 官方规则，混传会在生成前返回 400 、不计费）。
| 参数 | 类型 | 说明 |
| first_frame | file / url / base64 | 起始帧图片（可单独使用＝首帧图生视频）。别名： first_image_url |
| last_frame | file / url / base64 | 结束帧图片（与 first_frame 一起＝首尾过渡）。别名： last_image_url |
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-veo-3.1",
    "prompt": "镜头从清晨薄雾笼罩的湖面缓缓推进，雾气逐渐散去，远处倒影渐渐清晰",
    "seconds": "8",
    "size": "16:9",
    "video_resolution": "720p",
    "first_frame": "https://your-cdn.com/first.jpg",
    "last_frame":  "https://your-cdn.com/last.jpg"
  }'
```

### 多参考图（Reference Images）
用 reference_images 传入多张参考图，引导角色、风格与构图。 Veo 取用前若干张作参考 （标准版 firefly-veo-3.1 最多 3 张、Fast 版最多 2 张），支持图片 URL、base64 或 multipart（重复字段名传多张）。 与首尾帧模式互斥 ：同一请求不能同时传 first_frame / last_frame ，混传在生成前返回 400 、不计费。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-veo-3.1' \
  -F 'prompt=保持这几张参考图的人物形象与画面风格，让主体自然动起来' \
  -F 'seconds=6' \
  -F 'size=1280x720' \
  -F 'reference_images=@char.jpg;type=image/jpeg' \
  -F 'reference_images=@style.jpg;type=image/jpeg'
```
成功提交会返回异步任务，例如：
```
{
  "id": "task_xxx",
  "status": "queued",
  "model": "firefly-veo-3.1-fast",
  "progress": 0
}
```

### 轮询取片
```
curl -sS "$BASE_URL/v1/videos/task_xxx" \
  -H "Authorization: Bearer $TOKEN"
```
当响应中的 status 为 completed 时，读取 video_url ：
```
{
  "id": "task_xxx",
  "status": "completed",
  "model": "firefly-veo-3.1-fast",
  "video_url": "https://..."
}
```

### Python 完整请求
```
import time, requests

BASE = "https://newapi-2.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 提交（文生；图生改用 multipart 带 input_reference）
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "firefly-veo-3.1",
    "prompt": "日出时一盏彩色纸灯笼缓缓飘过安静的湖面，电影感镜头",
    "seconds": "6",
    "size": "1280x720"
}).json()
task_id = task.get("id") or task.get("task_id")

# 轮询
while True:
    time.sleep(6)
    s = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if s.get("status") == "completed":
        print("下载:", s["video_url"]); break
    if s.get("status") == "failed":
        print("失败:", s); break
```

### 注意事项
- 提交成功但还没有视频： 继续查询同一个任务 ID，直到状态变为 completed 或 failed 。
- 模型不可见或返回权限错误： 确认 API 令牌已开通 Firefly VEO 模型权限。
- 任务失败： 保留任务 ID 与错误响应，提交给技术支持排查；不要为同一任务并发重复提交。

### 建议
- 要带音频 用 firefly-veo-3.1 或 firefly-veo-3.1-fast-direct ； firefly-veo-3.1-fast 是静音档、无音轨。
- 画幅两套任选 ：像素式 size （如 1280x720 ）自动识别清晰度；官网式纵横比 16:9 需同时传 video_resolution 。
- 首尾帧与多参考图互斥 ：要过渡用 first_frame + last_frame ，要角色 / 风格一致用 reference_images ，别混用。
- 参考图用真实合规照片 ，含可识别真人面孔可能触发内容策略。

---

# Adobe Firefly · Seedance 2.0
来源：https://docs.oairegbox.cc/#sec-firefly-seedance

## Adobe Firefly · Seedance 2.0
Adobe Firefly 的 Seedance 2.0 与 Seedance 2.0 Fast 视频模型。支持 文生视频 与 单图生视频 ，使用 OpenAI 兼容的异步视频接口：提交任务后轮询，完成时读取 video_url 获取成片。 四档均原生自带音频 （对白 / 音效 / 环境音同步生成），无需额外参数。

### 模型与价格
| 模型 | 版本 | 固定输出分辨率 | 价格 |
| firefly-Seedance-2.0-fast-480p | Seedance 2.0 Fast | 480p | ¥0.10/秒 |
| firefly-Seedance-2.0-fast-720p | Seedance 2.0 Fast | 720p | ¥0.25/秒 |
| firefly-Seedance-2.0-480p | Seedance 2.0 标准版 | 480p | ¥0.15/秒 |
| firefly-Seedance-2.0-720p | Seedance 2.0 标准版 | 720p | ¥0.35/秒 |
模型名已固定输出分辨率； video_resolution 只能填写与所选模型一致的值，不能用 480p SKU 请求 720p 输出。

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc |
| 提交任务 | POST /v1/videos |
| 查询任务 | GET /v1/videos/{task_id} |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 成片交付 | 任务 status 为 completed 后，读取顶层 video_url |

### 已支持规格
| 参数 | 可用值 | 说明 |
| seconds / duration | 4 ~ 15 （任意整数） | 输出时长（秒）；Adobe 官方支持 4–15 秒 |
| video_resolution | 480p 、 720p | 必须与模型名的固定 SKU 相同 |
| size | 16:9 / 9:16 ，或下列精确像素 | 横竖画幅；也可使用 aspect_ratio |
| 输出档位 | 16:9 横版 | 9:16 竖版 |
| 480p | 854x480 | 480x854 |
| 720p | 1280x720 | 720x1280 |

### 核心参数
提交一张首帧参考图即可启用图生视频；不带图片则为文生视频。 input_reference 为单张首帧图。 若需首尾帧或多图 / 视频 / 音频参考，见下方“首尾帧”“全能参考（Omni）”两节。 可上传 JPEG/JPG、PNG、WebP。服务会按目标画幅进行居中裁切、缩放并转为 PNG 后提交；建议先按目标画幅准备主体清晰的图片，以免裁掉重要内容。
| 字段 | 类型 | 必填 | 说明 |
| model | string | 是 | 上表之一 |
| prompt | string | 是 | 描述运动、镜头和画面变化 |
| seconds | integer/string | 否 | 4 ~ 15 任意整数；默认 4 |
| video_resolution | string | 否 | 480p 或 720p，必须匹配模型 |
| size | string | 否 | 16:9 / 9:16，或精确输出像素 |
| input_reference | file | 图生时是 | 单张首帧图；使用 multipart/form-data 上传 |
| image_style | string | 否 | 可选风格化： 真人参考 → 漫剧角色 时传 anime （详见下方“参考图含真人脸 · image_style ”一节）； 留空 = 原图直发 ，想保留真人请勿传 |

### 提交方式
| 模式 | Content-Type | 参考素材 |
| 文生视频（T2V） | application/json | 无 |
| 图生 / 首尾帧 / 全能参考（Omni） | multipart/form-data （ -F ） | input_reference / first_frame + last_frame / reference_images · reference_videos · reference_audios |

### 示例：文生视频
```
BASE_URL="https://newapi-2.oairegbox.cc"
TOKEN="sk-xxx"

curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-Seedance-2.0-fast-480p",
    "prompt": "一盏纸灯笼在夜色湖面上缓缓漂过，水面反射暖色灯光，电影感镜头。",
    "seconds": 5,
    "video_resolution": "480p",
    "size": "854x480"
  }'
```

### 示例：单图生视频
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=让画面中的山间云雾缓慢流动，镜头轻微向前推进。' \
  -F 'seconds=5' \
  -F 'video_resolution=480p' \
  -F 'size=854x480' \
  -F 'input_reference=@frame.jpg;type=image/jpeg'
```

### 参考图含真人脸 · image_style 风格化（可选）
先分清你要哪种结果 ，再决定用不用这个参数：
- 要真人输出 （真人参考 → 生成的仍是真人）： 不要用 image_style 。请改用 三视图 / 多角度参考 的方式——把同一人物的正面、侧面、背面等多张清晰照片作为 多图参考 传入（见下方“全能参考（Omni）”的 仅多图参考 示例），既能提高“真人脸”过审率，又能保持真人形象。
- 要漫剧 / 动漫角色脸型 （真人参考 → 生成动漫角色）：传可选参数 image_style=anime 。网关会在提交 Adobe 前把你的 真人参考图整图风格化（动漫化） ，从而通过 Adobe 的“真人脸”内容审核，产出 漫剧风格 的角色视频。
| 参数 | 可用值 | 说明 |
| image_style | anime | 仅对 带参考图的图生视频（i2v） 生效：提交 Adobe 前把参考图转成 动漫 / 绘画风 ，用于把真人参考做成漫剧角色。 留空 = 不处理（原图直发） 。目前支持 anime 一种，后续按需增加。 |
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=参考图中的人物，转成漫剧角色在城市街头行走，日系动漫画风' \
  -F 'seconds=5' \
  -F 'video_resolution=480p' \
  -F 'size=854x480' \
  -F 'input_reference=@person.jpg;type=image/jpeg' \
  -F 'image_style=anime'
```

### 首尾帧（First / Last Frame）
提供 起始帧 和 结束帧 图片，Seedance 生成从首帧平滑过渡到尾帧的视频。用 first_frame 、 last_frame 两个字段，支持 multipart 文件、图片 URL 或 base64（ data:image/...;base64, ）。只传 first_frame 即为单首帧动画。 首尾帧模式与下方“全能参考”模式互斥，不能同一请求混用 （Adobe 官方规则）。
| 参数 | 类型 | 说明 |
| first_frame | file / url / base64 | 起始帧图片（可单独使用） |
| last_frame | file / url / base64 | 结束帧图片（与 first_frame 一起=首尾过渡） |
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=镜头从第一张画面平滑过渡到第二张画面，电影感运镜' \
  -F 'seconds=5' \
  -F 'size=854x480' \
  -F 'first_frame=@first.jpg;type=image/jpeg' \
  -F 'last_frame=@last.jpg;type=image/jpeg'
```

### 全能参考（Omni · 图 / 视频 / 音频）
Seedance 2.0 的核心能力：一次最多提供 9 张图 + 3 段视频 + 3 段音频 （总计 ≤ 9 个参考资产 ）作为风格、角色、构图、运镜、音效的引导。用 reference_images 、 reference_videos 、 reference_audios 传入，可在 prompt 里用文字说明各参考的作用。参考视频引导运动与氛围（不是直接动画化）。 与首尾帧模式互斥。
| 参数 | 数量上限 | 单文件上限 | 说明 |
| reference_images | 9 | 100 MiB | 参考图（风格 / 角色 / 构图） |
| reference_videos | 3 | 50 MiB | 参考视频（运镜 / 氛围，建议 2–15s） |
| reference_audios | 3 | 50 MiB | 参考音频（节奏 / 音效） |
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=参考图片的色调、视频的运镜、音频的节奏，生成一段电影感镜头' \
  -F 'seconds=5' \
  -F 'size=854x480' \
  -F 'reference_images=@style.jpg;type=image/jpeg' \
  -F 'reference_videos=@motion.mp4;type=video/mp4' \
  -F 'reference_audios=@beat.mp3;type=audio/mpeg'
```

#### 更多参考用法示例
① 仅多图参考 （角色/风格一致性，最多 9 张，重复字段名传多张）：
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=保持这几张参考图的人物形象与画面风格，让主体自然走动' \
  -F 'seconds=6' \
  -F 'size=854x480' \
  -F 'reference_images=@char1.jpg;type=image/jpeg' \
  -F 'reference_images=@char2.jpg;type=image/jpeg' \
  -F 'reference_images=@style.jpg;type=image/jpeg'
```
② 图 + 参考视频 （用视频引导运镜/氛围，不直接动画化）：
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-720p' \
  -F 'prompt=参考图片的主体，沿用参考视频的镜头运动方式生成' \
  -F 'seconds=5' \
  -F 'size=1280x720' \
  -F 'reference_images=@subject.jpg;type=image/jpeg' \
  -F 'reference_videos=@camera-move.mp4;type=video/mp4'
```
③ 图 + 参考音频 （用音频引导节奏/情绪）：
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=参考图片的场景，随音乐的舒缓节奏缓慢运镜' \
  -F 'seconds=8' \
  -F 'size=854x480' \
  -F 'reference_images=@scene.jpg;type=image/jpeg' \
  -F 'reference_audios=@music.mp3;type=audio/mpeg'
```
④ 仅首帧动画 （只给起始帧，让静图动起来）：
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Seedance-2.0-fast-480p' \
  -F 'prompt=让画面中的云雾缓慢流动，镜头轻微向前推进' \
  -F 'seconds=5' \
  -F 'size=854x480' \
  -F 'first_frame=@start.jpg;type=image/jpeg'
```
⑤ 标准版 720p + 图片 URL（JSON） ——参考图支持公网 URL / base64； 视频、音频仅支持 multipart 文件或 base64 （不接受 URL）：
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-Seedance-2.0-720p",
    "prompt": "参考这张图的色调，生成一段唯美空镜",
    "seconds": 8,
    "size": "1280x720",
    "reference_images": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]
  }'
```

### 轮询取片
```
curl -sS "$BASE_URL/v1/videos/task_xxx" \
  -H "Authorization: Bearer $TOKEN"
```
任务状态依次为 queued 、 in_progress 、 completed 或 failed 。当状态为 completed 时，读取响应中的 video_url ；建议每 5-10 秒轮询一次，不要为同一请求并发重复提交。

### Python 完整请求
```
import time, requests

BASE = "https://newapi-2.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 提交（文生；图生改用 multipart 带 input_reference）
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "firefly-Seedance-2.0-fast-480p",
    "prompt": "一盏纸灯笼在夜色湖面上缓缓漂过，电影感镜头",
    "seconds": 5,
    "video_resolution": "480p",
    "size": "854x480"
}).json()
task_id = task.get("id") or task.get("task_id")

# 轮询
while True:
    time.sleep(6)
    r = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if r.get("status") == "completed":
        print("下载:", r["video_url"]); break
    if r.get("status") == "failed":
        print("失败:", r); break
```

### 注意事项
- 四档全带音频 （AAC），原生同步生成对白 / 音效 / 环境音，无需额外参数、不额外计费。
- 模型名已固定分辨率 ：480p SKU 不能请求 720p 输出； video_resolution 须与模型一致。
- 参考素材 ：图支持 URL / base64 / 文件； 视频、音频仅接受文件或 base64，不收 http URL ；三类合计 ≤ 9 个。
- 首尾帧模式与全能参考模式 互斥 ；超量 / 超大 / 混用在生成前返回 400 、不计费。

### 建议
- 真人要真人 用三视图多图参考、别传 image_style ； 真人要漫剧脸 传 image_style=anime 。
- 按目标画幅裁好图 再传（服务端会居中裁切缩放），避免主体被裁掉。
- 输出侧审核为概率性，个别任务重试 1–2 次即可， 失败不计费 。

---

# Adobe Firefly · Kling 3.0
来源：https://docs.oairegbox.cc/#sec-firefly-kling

## Adobe Firefly · Kling 3.0
Adobe Firefly 的 Kling 3.0 与 Kling 3.0 Omni 视频模型。支持 文生视频 、 图生视频（首帧参考图） 与 Omni 多主体参考（ @元素 ，单次最多 3 个） ，使用 OpenAI 兼容的异步视频接口：提交任务后轮询，完成时读取顶层 video_url 获取成片。

### 模型与价格 · 按秒计费
| 模型 | 版本 | 清晰度 | 价格 | 时长 |
| firefly-Kling-3.0-720p | Kling 3.0 标准 | 720p | ¥0.045/秒 | 5–15 秒（自定义） |
| firefly-Kling-3.0-1080p | Kling 3.0 标准 | 1080p | ¥0.065/秒 | 5–15 秒（自定义） |
| firefly-Kling-3.0-Omni-720p | Kling 3.0 Omni（全能参考） | 720p | ¥0.08/秒 | 5–15 秒（自定义） |
| firefly-Kling-3.0-Omni-1080p | Kling 3.0 Omni（全能参考） | 1080p | ¥0.10/秒 | 5–15 秒（自定义） |

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc |
| 提交任务 | POST /v1/videos |
| 查询任务 | GET /v1/videos/{task_id} |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 任务模式 | 异步；提交成功仅表示任务已入队，需轮询 |
| 成片交付 | 任务 status 为 completed 后，读取顶层 video_url |

### 核心参数（参考 Adobe 官方）
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | 上表 4 个模型之一（区分大小写） |
| prompt | string | 是 | 画面、主体、动作、镜头与风格描述 |
| seconds / duration | string | 是 | "5" ~ "15" 任意整数；Adobe 官方支持自定义时长，最多 15 秒（标准与 Omni 同） |
| size | string | 是 | 输出 像素尺寸 宽x高 ；画幅（横/竖）与清晰度（720p/1080p）由像素自动识别（见下表） |
| input_reference | string / 文件 | 否 | 图生视频用 ：首帧参考图，支持图片 URL、base64 或 multipart 文件；带此参数时整个请求改用 multipart 表单 |
| @元素名 （写在 prompt 里） | prompt 内引用 | 否 | Omni 多主体参考用 ：先用 POST /v1/entities 把参考图创建成命名“元素”，再在 prompt 中用 @元素名 引用。 单个请求最多 3 个元素 （第 4 个起被系统拒： reference_elements: at most 3 items ）。详见下方“多主体参考”示例。仅 firefly-Kling-3.0-Omni-* 支持 |
| size （传这个） | 画幅 | 清晰度 |
| "1280x720" | 横版 16:9 | 720p |
| "720x1280" | 竖版 9:16 | 720p |
| "720x720" | 方形 1:1 | 720p |
| "1920x1080" | 横版 16:9 | 1080p |
| "1080x1920" | 竖版 9:16 | 1080p |
| "1080x1080" | 方形 1:1 | 1080p |

### 提交方式
| 模式 | 提交 | 参考素材 |
| 文生视频（T2V） | application/json | 无 |
| 图生视频（首帧） | multipart/form-data （ -F ） | input_reference （URL / base64 / 文件） |
| Omni 多主体参考 | 先 POST /v1/entities 建元素，再 JSON 内 @元素名 | 仅 firefly-Kling-3.0-Omni-* ，单次 ≤ 3 个元素 |

### 示例：文生视频
```
BASE_URL="https://newapi-2.oairegbox.cc"
TOKEN="sk-xxx"

curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-Kling-3.0-720p",
    "prompt": "一只雄鹰在金色夕阳下掠过雪山之巅，电影感镜头，缓慢推进。",
    "seconds": "5",
    "size": "1280x720"
  }'
```

### 示例：图生视频（首帧参考图 input_reference）
用 multipart 表单 带一张参考图作为首帧，其余参数一致。 input_reference 支持本地文件、图片 URL 或 base64。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-Kling-3.0-720p' \
  -F 'prompt=让画面中的主体自然动起来，镜头缓慢向前推进，保持构图。' \
  -F 'seconds=5' \
  -F 'size=1280x720' \
  -F 'input_reference=@frame.jpg;type=image/jpeg'
```

### 示例：Omni 多主体参考（ @元素 ，最多 3 个）
Kling 3.0 Omni 支持把参考图作为 命名“元素”（主体/角色/物体/场景） ，在 prompt 中用 @元素名 引用，让生成画面保持该主体的一致性。 单个视频请求最多引用 3 个元素 （第 4 个起会被系统拒绝： reference_elements: List should have at most 3 items ）。分两步：

#### 第 1 步：创建元素（ POST /v1/entities ）
每个元素用 1~4 张参考图构建（建议 4 张不同角度，效果更稳）。 type 取 character （角色）/ object （物体）/ location （场景）。
```
curl -sS -X POST "$BASE_URL/v1/entities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "type": "character",
    "images": [
      "https://your-cdn.com/alice_front.jpg",
      "https://your-cdn.com/alice_side.jpg"
    ]
  }'
```

#### 第 2 步：生成时用 @元素名 引用（最多 3 个）
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-Kling-3.0-Omni-720p",
    "prompt": "@Alice 和 @Bob 在 @Cafe 里相视而笑，暖色灯光，电影感镜头。",
    "seconds": "5",
    "size": "1280x720"
  }'
```

### 轮询取片
```
curl -sS "$BASE_URL/v1/videos/task_xxx" \
  -H "Authorization: Bearer $TOKEN"
```
当响应中的 status 为 completed 时，读取顶层 video_url （短期签名下载地址，请在有效期内下载或转存）。

### Python 完整请求
```
import time, requests

BASE = "https://newapi-2.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 提交（文生；图生改用 multipart 带 input_reference）
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "firefly-Kling-3.0-720p",
    "prompt": "一只雄鹰在金色夕阳下掠过雪山之巅，电影感镜头",
    "seconds": "5",
    "size": "1280x720"
}).json()
task_id = task.get("id") or task.get("task_id")

# 轮询
while True:
    time.sleep(6)
    r = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if r.get("status") == "completed":
        print("下载:", r["video_url"]); break
    if r.get("status") == "failed":
        print("失败:", r); break
```

### 注意事项
- model_not_found： 检查大小写，必须是 firefly-Kling-3.0-720p / firefly-Kling-3.0-Omni-1080p 等（ Kling / Omni 首字母大写）。
- 时长不支持： 标准版与 Omni 均支持 5 – 15 秒任意整数。
- 任务失败： 保留任务 ID 与错误响应交技术支持；不要为同一任务并发重复提交。

### 建议
- 要多主体一致 用 Omni 版：先 POST /v1/entities 建元素（每个 1–4 张、建议 4 张不同角度），再在 prompt 里 @元素名 引用。
- 清晰度按预算选 ：720p 便宜、1080p 更清晰；画幅用像素 size 或 aspect_ratio 均可。
- 模型名区分大小写 （ Kling / Omni 首字母大写），否则报 model_not_found 。

---

# Adobe Firefly · Gemini Omni Flash
来源：https://docs.oairegbox.cc/#sec-firefly-gemini-omni

## Adobe Firefly · Gemini Omni Flash
Google Gemini Omni Flash 视频模型，经 Adobe Firefly 接入。 同一个模型名支持三种模式，按你传入的素材自动切换 ：只传 prompt = 文生视频（T2V）；额外带一张参考图 = 图生视频（I2V）；额外带一段参考视频 = 视频生视频（V2V）。OpenAI 兼容异步接口：提交任务后轮询，完成时从响应顶层 video_url 获取成片。

### 模型与价格
| 模型 | 模式 | 时长 | 清晰度 | 计费 | 价格 |
| firefly-gemini-omni-720p | 文生 / 图生 / 视频生视频（自动） | 4 / 6 / 8 / 10 秒 | 720p | 按秒 | ¥0.20 / 秒 |

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc |
| 提交任务 | POST /v1/videos |
| 查询任务 | GET /v1/videos/{task_id} |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 任务模式 | 异步；提交成功仅表示任务已入队 |
| 成片交付 | 任务 status 为 completed 后，读取顶层 video_url |

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | 固定 firefly-gemini-omni-720p |
| prompt | string | 是 | 视频画面、主体、动作、镜头和风格描述 |
| seconds | string | 是 | 目标时长（秒），仅支持 "4" 、 "6" 、 "8" 、 "10" |
| size | string | 是 | 画幅，取 "1280x720" （横 720p）或 "720x1280" （竖 720p）；也接受纵横比 "16:9" / "9:16" 。仅 720p，无需传 video_resolution |
| video_resolution | string | 否 | 仅 "720p" ；传纵横比 size 时可选传，不传也默认 720p |
| input_reference | string / 文件 | 否 | 图生视频（I2V）用 ：参考图（首帧）。可传图片 URL、base64（ data:image/...;base64, ）或 multipart 文件（ @frame.jpg ）。带此参数时整个请求改用 multipart 表单提交（见下方示例）。首发支持 单张 参考图 |
| input_video | 文件 / base64 | 否 | 视频生视频（V2V）用 ：参考视频。 仅支持 multipart 文件（ @clip.mp4 ）或 base64（ data:video/mp4;base64, ）；不支持纯 http URL 。带此参数时整个请求改用 multipart 表单提交（见下方示例） |

#### size 取值与输出
| size | 画幅 | 清晰度 |
| "1280x720" 或 "16:9" | 横版 16:9 | 720p |
| "720x1280" 或 "9:16" | 竖版 9:16 | 720p |

### 提交方式
| 模式 | Content-Type | 参考素材 |
| 文生视频（T2V） | application/json | 无 |
| 图生视频（I2V） | multipart/form-data | input_reference （URL / base64 / 文件，单张） |
| 视频生视频（V2V） | multipart/form-data | input_video （ 仅文件 / base64，不收 http URL ） |

### 示例一：文生视频（T2V，JSON）
```
BASE_URL="https://newapi-2.oairegbox.cc"
TOKEN="sk-xxx"

curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gemini-omni-720p",
    "prompt": "日出时一只金毛小狗在草地上奔跑，柔和晨光，电影感镜头。",
    "seconds": "4",
    "size": "1280x720"
  }'
```

### 示例二：图生视频（I2V，带参考图 input_reference）
在文生的基础上，用 multipart 表单 额外带一张参考图作为首帧，其余参数（ seconds 、 size ）一致。 input_reference 支持 本地文件 、 图片 URL 或 base64 三种传法。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-gemini-omni-720p' \
  -F 'prompt=让画面里的小狗自然转头看向镜头并摇尾巴，镜头缓慢推进。' \
  -F 'seconds=4' \
  -F 'size=1280x720' \
  -F 'input_reference=@frame.jpg;type=image/jpeg'
```

### 示例三：视频生视频（V2V，带参考视频 input_video）
用 multipart 表单 带一段参考视频，模型在其基础上按 prompt 重新演绎（改风格、加动作等）。 input_video 仅支持本地文件（ @clip.mp4 ）或 base64，不支持纯 http URL。
```
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'model=firefly-gemini-omni-720p' \
  -F 'prompt=把这段片子改成水彩画风格，保留原有的运动。' \
  -F 'seconds=4' \
  -F 'size=1280x720' \
  -F 'input_video=@clip.mp4;type=video/mp4'
```

### 轮询取片
三种模式提交后都返回异步任务，轮询方式一致：
```
curl -sS "$BASE_URL/v1/videos/task_xxx" \
  -H "Authorization: Bearer $TOKEN"
```
当响应中的 status 为 completed 时，读取顶层 video_url ：
```
{
  "id": "task_xxx",
  "status": "completed",
  "model": "firefly-gemini-omni-720p",
  "video_url": "https://..."
}
```

### Python 完整请求
```
import time, requests

BASE = "https://newapi-2.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 提交（文生；I2V 用 multipart 带 input_reference，V2V 带 input_video）
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "firefly-gemini-omni-720p",
    "prompt": "日出时一只金毛小狗在草地上奔跑，柔和晨光",
    "seconds": "4",
    "size": "1280x720"
}).json()
task_id = task.get("id") or task.get("task_id")

# 轮询
while True:
    time.sleep(6)
    r = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if r.get("status") == "completed":
        print("下载:", r["video_url"]); break
    if r.get("status") == "failed":
        print("失败:", r); break
```

### 注意事项
- 时长仅四档： seconds 只接受 4 / 6 / 8 / 10 ，其它值会报错。
- V2V 视频来源： input_video 只收 multipart 文件或 base64 data URL， 不会下载 http 链接 ；传 http 链接会被忽略、退化为文生。
- I2V 参考图： 首发支持单张参考图作首帧。
- 无音频： 成片为静音输出，不含音频轨。
- 模型权限： 确认 API 令牌已开通 Firefly 分组权限；任务失败请保留任务 ID 与错误响应交技术支持，勿对同一任务并发重复提交。

### 建议
- 一模型三模式 ：只给 prompt =文生；加 input_reference =图生；加 input_video =视频生视频（同时给图和视频按 V2V）。
- V2V 视频只走文件 / base64 ，不下载 http 链接；传 http 会退化成文生。
- 成片无音频 （静音输出）；时长仅 4 / 6 / 8 / 10 四档。

---

# Adobe Firefly · GPT Image 2
来源：https://docs.oairegbox.cc/#sec-firefly-gpt-image

## Adobe Firefly · GPT Image 2
Adobe Firefly 的 GPT Image 2 文生图模型。客户侧只选择 画布尺寸（1K / 2K / 4K） ，服务端统一使用 medium 质量（Adobe detailLevel=3 ）。接口使用 OpenAI 兼容的 异步视频任务契约 ：提交任务后轮询，完成时从 video_url 下载 PNG 图片。

### 模型与价格
| 模型 | 画布尺寸 | 服务端质量 |
| firefly-gpt-image-1k | 1K | medium（固定） |
| firefly-gpt-image-2k | 2K | medium（固定） |
| firefly-gpt-image-4k | 4K | medium（固定） |

#### 质量策略
| 服务端质量 | Adobe detailLevel | 客户侧 |
| medium | 3 | 固定，不开放 quality 字段 |

### 实际输出像素
| 画幅 | 1k | 2k | 4k |
| 1:1 | 1024×1024 | 2048×2048 | 2880×2880 |
| 16:9 | 1088×608 | 2048×1136 | 3840×2128 |
| 9:16 | 608×1088 | 1136×2048 | 2128×3840 |
| 21:9 | 1248×528 | 2048×864 | 3840×1616 |
| 5:4 | 1024×816 | 2048×1648 | 3200×2576 |
| 4:3 | 1024×752 | 2048×1520 | 3328×2480 |
| 3:2 | 1024×672 | 2048×1360 | 3504×2352 |
重点： 质量不会改变像素尺寸。Adobe 有总像素和最小像素硬限制，所以宽幅 1K 的最长边可能大于 1024，这不是质量档变化。

### 画幅
通过 aspect_ratio （或 size ）选画幅，支持： auto 、 1:1 、 16:9 、 9:16 、 5:4 、 4:3 、 3:2 、 4:5 、 3:4 、 2:3 、 21:9 。不传默认 1:1 。

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc |
| 提交任务 | POST /v1/videos |
| 查询任务 | GET /v1/videos/{task_id} |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 成片交付 | 任务 status 为 completed 后，读取顶层 video_url |

### 核心参数
| 字段 | 类型 | 必填 | 说明 |
| model | string | 是 | 上表之一 |
| prompt | string | 是 | 图片描述 |
| aspect_ratio | string | 否 | 画幅，见上；默认 1:1 |

### 提交方式
| 模式 | 端点 | 参考素材 |
| 文生图 | POST /v1/videos （JSON，异步契约，输出 PNG） | 无 |
| 图生图 / 图片编辑（i2i） | 同一 POST /v1/videos （JSON） | reference_images 数组，每项 data:image/...;base64, ，最多 6 张 |

### curl 示例：提交与轮询
```
# 提交任务：1K + 16:9（质量由服务端固定为 medium）
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-1k","prompt":"a red apple on a white ceramic plate, studio daylight, no text","aspect_ratio":"16:9"}'

# 提交任务：1K + 1:1
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-1k","prompt":"a ceramic tea set on a wooden table, editorial product photo","aspect_ratio":"1:1"}'

# 提交任务：2K + 9:16
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-2k","prompt":"a quiet mountain lake at sunrise, natural colors","aspect_ratio":"9:16"}'

# 提交任务：2K + 16:9
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-2k","prompt":"a modern glass office beside a tree-lined street","aspect_ratio":"16:9"}'

# 提交任务：4K + 21:9
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-4k","prompt":"a cinematic coastal road under soft evening light","aspect_ratio":"21:9"}'

# 提交任务：4K + 16:9
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-4k","prompt":"a premium watch on black stone, controlled studio lighting","aspect_ratio":"16:9"}'

# 提交任务：4K + 4:3
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"firefly-gpt-image-4k","prompt":"a botanical still life in a glass vase","aspect_ratio":"4:3"}'

# 轮询：把 task_xxx 替换成提交响应中的 id
curl https://newapi-2.oairegbox.cc/v1/videos/task_xxx \
  -H "Authorization: Bearer $TOKEN"
# 完成时读取响应中的 video_url（PNG 图片直链）
```

### Python 完整请求
依赖： python -m pip install requests 。脚本只提交一次任务；提交成功后持续轮询同一个任务 ID，完成后把 PNG 保存到本地。不要在客户端超时后重新提交同一张图。
```
#!/usr/bin/env python3
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://newapi-2.oairegbox.cc"
TOKEN = os.environ["NEWAPI_TOKEN"]

request_body = {
    "model": "firefly-gpt-image-2k",
    "prompt": "a red apple on a white ceramic plate, studio daylight, no text",
    "aspect_ratio": "16:9",
}
headers = {"Authorization": f"Bearer {TOKEN}"}

with requests.Session() as client:
    # Submit exactly once. quality is intentionally omitted; the service uses medium.
    response = client.post(
        f"{BASE_URL}/v1/videos",
        headers={**headers, "Content-Type": "application/json"},
        json=request_body,
        timeout=60,
    )
    response.raise_for_status()
    submitted = response.json()
    task_id = submitted.get("id") or submitted.get("task_id")
    if not task_id:
        raise RuntimeError(f"submit response has no task id: {submitted}")
    print(f"submitted task={task_id}")

    started = time.monotonic()
    while True:
        if time.monotonic() - started > 900:
            raise TimeoutError(f"task {task_id} is still running; keep polling it")
        task = client.get(
            f"{BASE_URL}/v1/videos/{task_id}", headers=headers, timeout=30
        )
        task.raise_for_status()
        body = task.json()
        status = str(body.get("status") or body.get("state") or "").lower()
        print(f"status={status}")
        if status in {"failed", "failure", "error", "cancelled", "canceled"}:
            raise RuntimeError(f"task {task_id} failed: {body}")
        if status in {"completed", "succeeded", "success", "done"}:
            image_url = body.get("video_url") or body.get("url")
            if not image_url:
                raise RuntimeError(f"completed task has no video_url: {body}")
            break
        time.sleep(5)

    output = Path("firefly-2k-16x9.png")
    with client.get(image_url, headers=headers, stream=True, timeout=60) as download:
        download.raise_for_status()
        with output.open("wb") as file:
            for chunk in download.iter_content(1024 * 1024):
                if chunk:
                    file.write(chunk)
    print(f"saved {output} ({output.stat().st_size} bytes)")
```
运行前设置令牌： export NEWAPI_TOKEN="sk-你的令牌" 。把 model 改成 firefly-gpt-image-1k 或 firefly-gpt-image-4k 即可切换画布档位； aspect_ratio 可替换为本页支持的其它画幅。

#### shell 自动轮询
```
TASK_ID="task_xxx"
while true; do
  BODY=$(curl -fsS "https://newapi-2.oairegbox.cc/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $TOKEN") || exit 1
  STATUS=$(printf '%s' "$BODY" | jq -r '.status // empty')
  printf 'status=%s\n' "$STATUS"
  case "$STATUS" in
    completed|succeeded)
      printf '%s\n' "$BODY" | jq -r '.video_url // .data[0].url'
      break ;;
    failed|failure|error|cancelled|canceled)
      printf '%s\n' "$BODY" | jq . >&2
      exit 2 ;;
  esac
  sleep 10
done
```

### 图生图 / 图片编辑（i2i）
本通道支持两种带图用法，都走 同一套 /v1/videos ： 图生图 （传 1-6 张参考图，参考其风格 / 主体生成新图）与 图片编辑 （传原图，改背景 / 换元素 / 局部修改）。两者 请求格式完全一样 ，区别只在参考图张数与 prompt 的意图——都是在 JSON 请求体里加一个 reference_images 参考图数组；其余字段（ model / aspect_ratio ）、轮询方式、从 video_url 下载 PNG，都与文生图一致。
| 字段 | 类型 | 必填 | 说明 |
| reference_images | 数组 | 图生图/编辑必填 | 原图 / 参考图列表，每项为 data:image/...;base64, 内联的 Base64 图片。 单张也要放进数组 （直接传字符串会 400）。最多 6 张。字段名也可用 images 。 |
| prompt | string | 是 | 你要如何编辑，例如“把背景换成海边日落，人物主体保持不变” |
| model / aspect_ratio | — | 同文生图 | 与本页文生图一致（ firefly-gpt-image-1k/2k/4k + 画幅） |
```
# ① 图生图：参考图 + 描述 → 生成新图（参考风格 / 主体，可传 1-6 张）
REF1="data:image/png;base64,$(base64 < ref1.png | tr -d '\n')"
REF2="data:image/png;base64,$(base64 < ref2.png | tr -d '\n')"
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-2k",
    "prompt": "参考这些图的画风，画一只戴宇航头盔的柴犬，居中构图",
    "aspect_ratio": "1:1",
    "reference_images": ["'"$REF1"'", "'"$REF2"'"]
  }'

# ② 图片编辑：原图 + 描述 → 改后的图（reference_images 为 Base64 data URI 数组，单张也用数组）
IMG_B64="data:image/png;base64,$(base64 < input.png | tr -d '\n')"
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-2k",
    "prompt": "把背景换成海边日落，人物主体保持不变",
    "aspect_ratio": "1:1",
    "reference_images": ["'"$IMG_B64"'"]
  }'

# 提交返回 {"id":"task_xxx", ...}；随后轮询（与文生图完全相同）：
curl https://newapi-2.oairegbox.cc/v1/videos/task_xxx \
  -H "Authorization: Bearer $TOKEN"
# status=completed 后，读响应里的 video_url —— 即改后图片的 PNG 直链
```

### 注意事项
- 质量固定 medium （Adobe detailLevel=3），客户端 不传 quality ；质量不改变输出像素。
- 宽幅 1K 的最长边可能大于 1024（Adobe 总像素 / 最小像素硬限制），非质量档变化。
- 图生图 / 编辑参考图 只接受 base64 内联，不支持 multipart 文件 ；含真人脸会被 Adobe 审核拒绝（解法见错误码页 image_style ）。
- 不要重复提交已被接受的任务 ；客户端超时继续轮询原 task，失败按控制台账单为准。

### 建议
- 按画布档选价 ：1K / 2K / 4K 只改画布尺寸、质量恒 medium；实际扣点以控制台结算为准。
- 要精确构图 先用 aspect_ratio 定画幅（默认 1:1），对照「实际输出像素」表核对最终尺寸。
- 图生图 / 编辑 把参考图转 data:image/...;base64, 放进 reference_images 数组（单张也用数组）。

---

# Adobe Firefly · 错误码 & 审核问题归档
来源：https://docs.oairegbox.cc/#sec-firefly-errors

## Adobe Firefly · 错误码 & 审核问题归档
Adobe Firefly 的内容审核较严格，视频任务失败大多来自 Adobe 侧的内容审核 或 输入不合规 ，而非网关故障。收到失败后请 先看错误类型判断能否重试 ：内容审核 / 参数类属 确定性失败 （同样输入重试必然再失败，需改输入）；账号 / 过载类属 可自动恢复 （网关会自动换号或重试，通常自愈）。 失败不计费。

### 一、内容审核类（Adobe 拒绝 · 重试无效 · 需改输入）
| 错误 | 触发 | 返回提示（示例） | 处理 |
| 参考图含真人脸 reference_image_privacy_error | 参考图 / 首帧里出现 真实人物面孔 | 参考图中包含真人面孔，Adobe 内容策略拒绝生成… | 换成不含真人脸的参考图；确需用真人图时，加可选参数 image_style=anime （见下）让网关先把参考图 风格化（动漫化） 再生成 |
| 提示词不安全 prompt_unsafe | 提示词含 Adobe 判定的 不适宜内容 （暴力 / 成人 / 名人 / 品牌等） | 提示词被 Adobe 内容安全策略判定为不适宜… | 改写提示词，去掉敏感 / 名人 / 品牌 / 违规描述 |
| 生成结果不安全 video_unsafe | 成片被 Adobe 事后审核 判定不安全（提交时未拦、生成后拒绝） | 请求被 Adobe 内容策略拒绝（video_unsafe）… | 调整提示词或更换随机种子后重试 |
| 音频疑似版权 native audio copyright | 带音频 的模型（如 Seedance）生成的音频被 Adobe 判 可能涉版权 | Adobe 判定本次生成的音频可能涉及版权限制… | 调整提示词或 更换参考素材 后重试（尽量避免具体歌曲 / 台词 / 品牌音效等易触发版权的描述） |

### 参考图含真人脸的解法 · image_style 风格化（可选）
参考图真人脸 是最常见的审核拒绝之一。确需用 真人照片 做图生视频（i2v）时，可加一个 可选参数 image_style ：网关会在提交 Adobe 前把你的参考图 整图风格化 （转成明显非真实照片的画风），从而通过 Adobe 的“真人脸”内容审核。 不传 image_style 时行为完全不变（原图直发） ——是否风格化的主动权在你。
| 参数 | 取值 | 说明 |
| image_style | anime | 把参考图转成 动漫 / 绘画风 后再生成；仅对 带参考图的图生视频（i2v） 生效，适用于 Seedance / VEO / Kling / Gemini-Omni。 留空 = 不处理 。目前支持 anime 一种，后续按需增加。 |
作为 顶层字段 传（与 prompt / model / seconds 同级）。示例（multipart）：
```
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -F model=firefly-Seedance-2.0-fast-480p -F seconds=4 -F "size=9:16" \
  -F prompt="镜头缓缓推近，人物自然微笑" \
  -F input_reference=@person.jpg \
  -F image_style=anime
```

### 二、输入 / 参数不合规（确定性失败 · 需改请求）
| 错误 | 触发 | 处理 |
| 参考图无法识别 cannot identify image file | 传入的参考图 不是有效图片 （文件损坏 / 非图片 / base64 截断错误） | 确认图片能正常打开；base64 用完整 data:image/...;base64, 前缀 |
| 参考图 URL 不合规 Only http/https or data URL images are supported / fetch image_url … 404 | 参考图 URL 非 http(s) / data，或该 URL 404 取不到 | 用可公开访问的 http(s) 直链，或改用 base64 / 文件上传 |
| 参考图数量超限 validation_error … at most N items | 该模型不支持多参考图或超过上限 | 按对应模型文档的参考图上限提交 |
| 提示词过长 prompt: at most 2500 characters | prompt 超过 2500 字符 | 精简提示词到 2500 字符内 |
| 画幅 / 时长参数冲突 | size （横）与 aspect_ratio （竖）互相矛盾；或时长档位不支持 | 见各模型页参数说明； 时长只认 seconds ； size 传纵横比时必带 video_resolution |

### 三、账号 / 权限 / 配额（多为可自动恢复）
| 错误 | 含义 | 处理 |
| 模型访问被拒 Adobe model access denied | 当前账号 无该模型权限 或 无音频权限 （如普通档请求带音频的模型）。网关会 自动换号重试 | 多数自动恢复； 持续 失败说明该模型 / 该内容需 积分档账号或特定权限 ，请联系我们 |
| 积分不足 / 耗尽 taste_exhausted / credit balance below cost | 该账号积分不足以支撑本次生成，网关自动改用其它账号 | 一般自动恢复；整体积分紧张时联系我们补充 |
| 限流 rate_limit / 429 | 账号短时请求过密 | 稍后重试并降低并发 |

### 四、临时 / 基础设施（网关自动重试 · 通常自愈）
| 错误 | 含义 | 处理 |
| 服务过载 408 system under load | Adobe 服务瞬时过载 | 网关自动重试；持续可稍后再试 |
| 服务内部错误 Unknown internal error | Adobe 生成侧瞬时内部错误 | 网关自动重试； 重试后仍失败 再联系我们 |
| 超时 timeout / 参考图下载超时 | 生成超时，或 参考图 URL 下载慢 / 失败 | 重试；参考图尽量用稳定直链或直接上传文件 |

---

# Seedance 自定义线路
来源：https://docs.oairegbox.cc/#sec-seedance-custom

## Seedance 自定义线路
字节跳动 Seedance 系列的 自定义线路 ，与「Seedance 官方直连」相互独立、单独维护。共 4 个模型 ： sd-2.0-mini / sd-2.0-fast / sd-2.0-standard 与新一代 sd-2.5 。支持 480p / 720p 两档清晰度 ，使用 OpenAI 兼容的异步视频接口：提交任务后轮询，完成时读取 video_url 获取成片。各模型调用方式完全一致，切换只需改 model 字段。

### 模型与价格
| 模型 | 480p | 720p | 时长 | 计费 | 定位 |
| sd-2.0-mini | ¥3.50/条 | ¥4.50/条 | 固定 15 秒 | 按次 | 经济档，走量首选 |
| sd-2.0-fast | ¥4.20/条 | ¥6.70/条 | 固定 15 秒 | 按次 | 快速出片，性价比高 |
| sd-2.0-standard | ¥5.20/条 | ¥8.50/条 | 固定 15 秒 | 按次 | 标准质量，画质更佳 |
| sd-2.5 | ¥0.44/秒 | ¥0.80/秒 | 默认 15 秒 · 可自定义 | 按秒 | 新一代 2.5，按秒计费更灵活 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （JSON） |
| 轮询进度 | GET /v1/videos/{task_id} |
| 下载成片 | 完成后响应里的 video_url （可直接下载 / 嵌入的直链） |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | sd-videos （智能 auto 分组亦可路由） |

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | sd-2.0-mini / sd-2.0-fast / sd-2.0-standard / sd-2.5 之一 |
| prompt | string | 是 | 视频描述提示词（文生视频） |
| aspect_ratio | string | 否 | 画幅： 16:9 （默认）、 9:16 、 1:1 ；也接受 size （如 1280x720 ），系统就近吸附到这三种 |
| resolution | string | 否 | 清晰度： 480p / 720p （默认 720p ），两档价格不同、见模型价格表 |
| duration | integer | 否 | 时长秒数， 仅 sd-2.5 生效 （默认 15 秒）； sd-2.0-* 固定 15 秒、传入无效 |
| referenceImages | array | 否 | 参考图（图生视频），元素为公网 URL 或 data:image/...;base64, ；可传多张 |
| referenceVideos | array | 否 | 参考视频，公网 URL 或 base64 |
| referenceAudios | array | 否 | 参考音频，公网 URL 或 base64 |

### 示例请求
```
# 文生视频（sd-2.0-standard，固定 15 秒）
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"sd-2.0-standard","prompt":"雨夜霓虹街道，镜头缓慢推进，电影感光影","aspect_ratio":"16:9"}'

# sd-2.5 按秒计费（自定义时长、480p 更省）
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"sd-2.5","prompt":"海边日落，海浪轻拍礁石","resolution":"480p","aspect_ratio":"16:9","duration":10}'

# 图生视频（referenceImages 参考图）
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"sd-2.0-fast","prompt":"让画面动起来","referenceImages":["https://cdn.example.com/photo.jpg"]}'
```

### 轮询取片
```
curl https://YOUR_BASE/v1/videos/TASK_ID -H "Authorization: Bearer sk-xxx"
# status=completed 后用响应里的 video_url 直链下载
curl -L "VIDEO_URL" -o result.mp4
```

### Python 完整请求
```
import time, requests
BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-你的sd-videos令牌", "Content-Type": "application/json"}
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "sd-2.0-standard",
    "prompt": "雨夜霓虹街道，镜头缓慢推进，电影感光影",
    "aspect_ratio": "16:9",
}).json()
tid = task["task_id"]
while True:
    r = requests.get(f"{BASE}/videos/{tid}", headers=H).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(5)
url = r.get("video_url") or (r.get("data") or [{}])[0].get("url")
open("seedance.mp4", "wb").write(requests.get(url).content)
```

### 注意事项
- 清晰度 ：用 resolution 选 480p / 720p （默认 720p ），两档价格不同、见模型价格表。
- 时长 ： sd-2.0-mini/fast/standard 单次固定 15 秒（按次计费）； sd-2.5 可用 duration 自定义时长（按秒计费）。
- 画幅 仅支持 16:9 / 9:16 / 1:1 三种，其它比例会就近吸附；竖屏传 aspect_ratio":"9:16" 。
- 下载 video_url 为直链，请及时转存。 失败不计费。

---

# Seedance 2.5 官方直连 Video
来源：https://docs.oairegbox.cc/#sec-seedance25

## Seedance 2.5 官方直连 Video

### 模型与价格
| 档位 | 文生 / 图生（无参考视频）¥/百万token | 视频编辑（带参考视频）¥/百万token | 折合每秒（视频编辑特惠） | 折合每秒（纯文/图生） | 典型 5 秒预计 |
| 720p · doubao-seedance-2.5-720p | ¥56.00 ¥70 （8 折） | ¥33.60 ¥42 （8 折） | 约 ¥0.73/秒 | 约 ¥1.21/秒 | 约 ¥3.63 ~ ¥6.05 |
| 1080p · doubao-seedance-2.5-1080p | ¥61.60 ¥77 （8 折） | ¥36.80 ¥46 （8 折） | 约 ¥1.79/秒 | 约 ¥2.99/秒 | 约 ¥8.94 ~ ¥14.97 |

#### 💰 预扣冻结额度与最低测试充值参考
| 模型 | 无视频预扣/秒 | 4秒预扣 | 5秒预扣 | 8秒预扣 | 5秒预计实扣（差额自动退回） | 视频编辑（含视频）5秒预扣 | 首次测试建议充值 |
| doubao-seedance-2.5-720p | ¥2.80/秒 | ¥11.20 | ¥14.00 | ¥22.40 | 约 ¥6.05（含视频约 ¥3.63） | ¥8.40（¥1.68/秒） | ¥15 ～ ¥30 |
| doubao-seedance-2.5-1080p | ¥6.16/秒 | ¥24.64 | ¥30.80 | ¥49.28 | 约 ¥14.97（含视频约 ¥8.94） | ¥18.40（¥3.68/秒） | ¥35 ～ ¥65 |

### 三种模式
| 模式 | 怎么触发 | seconds | 参考媒体（放 metadata ） |
| 文生视频 T2V | 只传 prompt ，不带任何参考素材 | 4–30， 自选 | 无 |
| 图生视频 I2V | 带参考图 | 4–30， 自选 | reference_images |
| 视频编辑 V2V | 带参考视频 | 必须 = 参考视频时长 | reference_videos |

### 接口信息
| 项 | 说明 |
| 提交端点 | POST /v1/videos 或 POST /v1/video/generations （标准 JSON，双端点完全等价兼容） |
| 轮询端点 | GET /v1/videos/{task_id} 或 GET /v1/video/generations/{task_id} |
| 视频直出预览 | GET /v1/videos/{task_id}/content （带 Bearer 令牌鉴权 302 重定向流式返回成片） |
| 下载成片 | 完成后响应里的 video_url （官方高速下载直链） |
| 鉴权方式 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Doubao （或 auto 智能路由分组） |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | doubao-seedance-2.5-720p 或 doubao-seedance-2.5-1080p （分辨率即档位） |
| prompt | string | 是 | - | 生成 / 编辑描述（如"一只橘猫在草地奔跑""改成夜景赛博朋克风格"）。无我方硬性长度上限 |
| seconds | string | 是 | - | 字符串 ，范围 4–30。文生 / 图生自选； 视频编辑必须 = 参考视频时长 |
| metadata.reference_images | array(URL / base64) | 否 | - | 图生视频用。 公网图片 URL 或 base64 data-URI， ≤30 张 ；放 metadata 内 |
| metadata.reference_videos | array(URL / base64) | 否 | - | 视频编辑用。 公网 mp4 URL 或 base64，单个 4–30 秒、分辨率 ≤ 档位， ≤10 个 （首个决定输出时长 / 画幅）；放 metadata 内 |
| metadata.reference_audios | array(URL / base64) | 否 | - | 配乐 / 音效参考，公网 URL 或 base64， ≤10 个 ；放 metadata 内 |

### 提交方式
JSON（ POST /v1/videos ）。 三种模式由素材自动切换 ：不带参考素材 = 文生视频； metadata.reference_images 带图 = 图生视频； metadata.reference_videos 带视频 = 视频编辑。 所有参考媒体（图 / 视频 / 音频）都放 metadata ，用公网 URL 或 base64 data-URI，不支持 multipart 文件上传 （URL 须无需登录即可下载）。默认生成音频。

### 示例请求
```
# ① 文生视频：只传 prompt + seconds（字符串）+ 模型名（分辨率自带）
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2.5-720p","prompt":"一只橘猫在草地上奔跑，阳光明媚","seconds":"8"}'

# ② 图生视频：metadata.reference_images 放参考图（公网 URL 或 base64）
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2.5-720p","prompt":"镜头缓慢推进，光线渐暗","seconds":"8",
       "metadata":{"reference_images":["https://你的图/first.jpg"]}}'

# ③ 视频编辑：metadata.reference_videos 放参考视频；seconds 必须=参考视频时长
curl -X POST https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2.5-1080p","prompt":"把画面改成水彩画风格，柔和色调","seconds":"8",
       "metadata":{"reference_videos":["https://你的视频/clip.mp4"]}}'
```

### 轮询取片
```
curl https://YOUR_BASE/v1/videos/TASK_ID -H "Authorization: Bearer $TOKEN"
# status=completed 后用 video_url 下载
curl -L "VIDEO_URL" -o result.mp4
```

### Python 完整请求
```
import time, requests
BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-你的Seedance令牌", "Content-Type": "application/json"}
# 文生视频；图生 / 视频编辑：在 metadata 里加 reference_images / reference_videos
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "doubao-seedance-2.5-720p",
    "prompt": "一只橘猫在草地上奔跑，阳光明媚",
    "seconds": "8",   # 字符串；视频编辑时必须 = 参考视频时长
    # "metadata": {"reference_images": ["https://你的图/first.jpg"]},   # 图生视频
    # "metadata": {"reference_videos": ["https://你的视频/clip.mp4"]},  # 视频编辑
}).json()
tid = task["task_id"]
while True:
    r = requests.get(f"{BASE}/videos/{tid}", headers=H).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(5)
url = r.get("video_url") or (r.get("data") or [{}])[0].get("url")
open("seedance25.mp4", "wb").write(requests.get(url).content)
```

### 注意事项
- 三种模式一个模型名 ：不带参考素材 = 文生视频； metadata.reference_images = 图生视频； metadata.reference_videos = 视频编辑。分辨率由模型名（720p / 1080p）决定。
- ⚠️ 视频编辑时 seconds 必须等于参考视频时长 ，否则报错并提示正确秒数（不产任务、不计费）； 文生 / 图生的 seconds 在 4–30 自选 。 seconds 传 字符串 。
- 参考媒体统一放 metadata 、用公网 URL 或 base64 data-URI，不支持 multipart 文件上传 ；URL 须无需登录即可下载。单次上限 30 图 + 10 视频 + 10 音频。
- 参考视频须 mp4、单个 4–30 秒、分辨率不超过档位（720p ≤1280×720、1080p ≤1920×1080），超出被拒；编辑高清源选 1080p 档。
- ⚠️ 价格分两档 ：文生 / 图生（无参考视频）单价高于视频编辑（带参考视频）； 以实际返回的 token 用量结算 ，可在控制台任务详情核对。
- ⚠️ 配音音色 / 性别跟随画面人物，不跟随上传的参考音频 ： generate_audio 为画面人物合成配音，上传女声不会把男性角色改成女声；想要女声请让画面人物为女性。

### 多模态输入 · 官方素材要求

#### 参考图要求
| 项 | 要求 |
| 传入方式 | 图片 URL、图片 Base64 编码 |
| 图片格式 | jpeg、png、webp、bmp、tif、gif； Seedance 2.0 及以上系列另支持 heic、heif |
| 宽高比（宽/高） | (0.4, 2.5) |
| 边长（px） | (300, 6000) |
| 大小 | 单张图片 < 30MB；请求体 ≤ 64MB。 大文件请勿使用 Base64 编码 |

#### 参考视频要求
| 项 | 要求 |
| 传入方式 | 视频 URL（须无需登录即可下载）或 Base64 data-URI，放 metadata.reference_videos |
| 视频格式 | mp4、mov（支持编码见下表） |
| 分辨率 | 720p、1080p（≤ 所选档位） |
| 宽高比（宽/高） | [0.4, 2.5] |
| 边长（px） | [300, 6000] |
| 总像素数 | 宽 × 高 ∈ [409600（640×640）, 2086876（2206×946）] |
| 大小 | 单个视频 ≤ 50MB |
| 帧率（FPS） | [24, 60] |
| 容器格式 | 常用扩展名 | MIME | 支持编码 |
| MP4 | .mp4 | video/mp4 | 视频：H.264/AVC、H.265/HEVC；音频：AAC、MP3 |
| QuickTime | .mov | video/quicktime | 视频：H.264/AVC、H.265/HEVC |

#### 参考音频要求
| 项 | 要求 |
| 传入方式 | 音频 URL、音频 Base64 编码 |
| 音频格式 | wav、mp3 |
| 大小 | 单个音频 ≤ 15MB；请求体 ≤ 64MB。 大文件请勿使用 Base64 编码 |

#### 保存时间
| 对象 | 保存时长 |
| 任务记录 | 保存 7 天，查询区间 [T−7天, T)，T 为请求发起时刻的 UTC 秒级时间戳 |
| 视频 URL | 保存 24 小时，超时后无法访问，请及时下载或转存 |

### 建议
- 文生 / 图生 ： seconds 在 4–30 自选；想要更稳的风格 / 主体，用 metadata.reference_images 带 1–2 张参考图。
- 视频编辑 ：先截好要编辑的关键片段（4–30 秒）， seconds 填该片段实际秒数；1080p 高清源用 doubao-seedance-2.5-1080p ，720p 源用 720p 档更省。
- 提示词写清"要什么风格 / 保留什么"，编辑 / 图生类配参考图能更稳定地锁定风格。

---

# Grok 视频
来源：https://docs.oairegbox.cc/#sec-grok

## Grok 视频
基于 xAI Grok Imagine 官方接口的视频生成，OpenAI 兼容异步接口。 三个模型 ： grok-imagine-video （1.0，文生 / 图生视频）、 grok-imagine-video-1.5-preview （1.5 代，画面质感更好）、 grok-imagine-video-6s （固定 6 秒 / 480p，最省钱）。 带参考图即图生视频，不带图则为纯文生视频 （1.5 建议带图）。

### 模型与价格
| 模型 | 分辨率(resolution) | 计费 | 价格 |
| grok-imagine-video | 480p（默认） | 按秒 | ¥0.05 / 秒 |
| grok-imagine-video | 720p | 按秒 | ¥0.065 / 秒 |
| grok-imagine-video-1.5-preview | 480p | 按秒 | ¥0.058 / 秒 |
| grok-imagine-video-1.5-preview | 720p（ 推荐 ） | 按秒 | ¥0.12 / 秒 |
| grok-imagine-video-1.5-preview | 1080p 高清 | 按秒 | ¥0.15 / 秒 |
| grok-imagine-video-6s | 固定 480p（不可调） | 按次 | ¥0.15 / 条 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （JSON） |
| 轮询进度 | GET /v1/videos/{task_id} ， status=completed 时返回 video_url |
| 下载成片 | 轮询返回的 video_url 直接 GET 下载（地址已脱敏） |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | xAI 或 auto （智能路由）分组均可 |

### 核心参数
| 参数 | 取值 | 默认 | 说明 |
| model | grok-imagine-video （1.0）/ grok-imagine-video-1.5-preview （1.5）/ grok-imagine-video-6s （6 秒定档） | - | 必填。 三个模型名 ；1.0 / 1.5 的分辨率用 resolution 参数， -6s 固定 480p / 6 秒（见文末专项说明） |
| prompt | 文本 | - | 必填，画面 / 运动描述 |
| image | 公网 URL 或 base64 Data URI | - | 可选。 单张首帧 ；带图=图生视频； grok-imagine-video 不带图=纯文生视频， grok-imagine-video-1.5-preview 建议带图 |
| reference_images | URL 数组 ，最多 7 张 | - | 可选， 多张参考图 （图生视频）。仅 grok-imagine-video-1.5-preview 的 480p / 720p 生效；⚠️ 1080p 不支持多图 （见下）。单张请用 image |
| seconds | 字符串， 1 ~ 15 | 6 | 视频时长（秒）。 全系按秒计费 ：费用 = 单价 × 秒数（1.0 与 1.5 系列均按秒） |
| aspect_ratio | 16:9 （横屏）/ 9:16 （竖屏）/ 1:1 （方屏） | 16:9 | 可选，画幅比例。⚠️ Grok 视频仅支持此 3 种画幅 （不支持 3:4、4:3 等；传入不支持比例官方将自动回退为 16:9 横屏）。手机竖版或电商主图请用 9:16 |
| resolution | 480p / 720p （1.5-preview 另 1080p ） | 480p | 决定分辨率与单价 （见上表）。⚠️ grok-imagine-video-1.5-preview 的 1080p 只支持单张首帧 image ，不支持多图 reference_images |
| size | 如 720x1280 / 1024x1024 | - | 旧字段，已兼容 ：自动换算为最接近的 aspect_ratio （避免"请求竖屏却出横屏"）；也支持 portrait / landscape / square 等词 |

### 提交方式（传图 · 单张首帧 vs 多张参考图）
i2v 的参考图通过 image 字段传入，支持两种写法：
| 方式 | 写法 | 说明 |
| 公网 URL | "image": "https://.../a.jpg" | 公网可直接 GET 的图片直链（不能是需登录 / 内网 / 拦爬虫的链接） |
| base64 Data URI | "image": "data:image/jpeg;base64,/9j/4AAQ..." | 须带 data: 前缀 |
图片格式 JPG / PNG / WebP。

#### 单张首帧 vs 多张参考图
- 单张首帧 ：用 image （字符串，一个 URL 或 base64）。
- 多张参考图 ：用 reference_images （URL 数组 ）， grok-imagine-video-1.5-preview 最多 7 张 ，模型综合多张参考出片。示例： "reference_images": ["https://.../a.jpg", "https://.../b.jpg"]
字段名兼容 ：单图推荐 image 、多图用 reference_images ； image_url / image_reference / images / image_urls / input_reference 等写法 也已兼容 （服务端自动识别为参考图，不会退化成纯文生视频）。

### 示例请求
```
# 文生视频（grok-imagine-video，不带图）
curl https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "灯塔在日落时分，海浪拍打礁石，电影感镜头",
    "seconds": "6",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
# => {"task_id":"task_xxx","status":"queued",...}

# 图生视频（grok-imagine-video-1.5-preview + resolution=720p，带 image）
curl https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "轻微镜头推移，画面自然生动",
    "image": "https://your-public-image.jpg",
    "seconds": "6"
  }'

# 多图参考（grok-imagine-video-1.5-preview + resolution=720p，最多 7 张；1080p 不支持多图）
curl https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "融合多张参考图的场景，电影感转场",
    "reference_images": ["https://img-a.jpg", "https://img-b.jpg"],
    "seconds": "6"
  }'
```

### 轮询取片
```
# 轮询直到 status=completed，取 video_url
curl https://YOUR_BASE/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-xxx"
# => {"status":"completed","video_url":"https://.../xxx.mp4",...}
```
轮询到 completed 后取 video_url 直接下载成片；下载地址已脱敏，不暴露源站域名。轮询间隔建议 3-5 秒。

### Python 完整请求
```
import time, requests

BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 提交（图生视频，1.5 代 720p）
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "轻微镜头推移，画面自然生动",
    "image": "https://your-public-image.jpg",
    "seconds": "6"
}).json()
task_id = task["task_id"]

# 轮询
while True:
    time.sleep(4)
    s = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if s.get("status") == "completed":
        print("下载:", s["video_url"])
        break
    if s.get("status") == "failed":
        print("失败:", s.get("error"))
        break
```

### 注意事项
- 计费（全系按秒，费用 = 单价 × 秒数） ： grok-imagine-video （1.0）480p / 720p = ¥0.05 / 0.065 每秒； grok-imagine-video-1.5-preview 480p / 720p / 1080p = ¥0.058 / 0.12 / 0.15 每秒； 失败不计费
- seconds 取 1 ~ 15 ；1.5-preview 分辨率 由 resolution 参数决定 （ 480p / 720p / 1080p ）
- 多张参考图 ： grok-imagine-video-1.5-preview （480p / 720p）用 reference_images 数组， 最多 7 张 ；单张首帧用 image
- ⚠️ 1080p 仅支持单张首帧 image ， 不支持多图 reference_images （传了也只取第一张作首帧）
- 图生视频的 image 须为 公网可直接抓取 的 URL 或 base64 Data URI；需登录 / 内网 / 拦爬虫（如部分维基）的链接会失败
- grok-imagine-video 不带图为文生视频； grok-imagine-video-1.5-preview 为图生视频，建议带 image
- 客户端超时建议 ≥ 300 秒；轮询间隔建议 3-5 秒
- ⚠️ 视频画幅与生图不同 ：Grok 生图支持 3:4 / 4:3 / 2:3 等画幅，但 Grok 视频官方底层仅支持 16:9 、 9:16 、 1:1 。如需 3:4 比例视频，建议设置 aspect_ratio: "9:16" 生成后在本地裁切，切勿传 3:4 以免官方自动回退至横屏。

### 建议
- 1.5 代优先带参考图 ： grok-imagine-video-1.5-preview 定位图生视频，带一张清晰首帧 image 出片更稳、质感更好；纯文生优先用 grok-imagine-video 。
- 要 1080p 就别传多图 ： -1080p 只认单张首帧，需要多张参考时用 -720p + reference_images 。
- 画幅用 aspect_ratio （三选一） ：推荐直接使用 aspect_ratio （ 9:16 竖屏 / 16:9 横屏 / 1:1 方屏），避免使用非标准比例； size 仅为兼容旧客户端保留。
- 内容合规 ：避开暴露 / 未成年 / 血腥暴力等敏感内容，否则被内容安全拦截（不计费）。

### grok-imagine-video-6s · 6 秒定档（最省钱）专项说明
grok-imagine-video-6s ：Grok Imagine 的单段短视频， 固定输出 6 秒 / 480p 档 、 按次计费 ¥0.15/条 。文生（只给提示词）与图生（带参考图、运动跟随提示词）都支持；与其它 Grok 视频同一 /v1/videos 通道， JSON body 与 multipart 表单均可提交 。
- 时长固定 6 秒、分辨率固定 480p 档 ；传 seconds / resolution 均被忽略。
- 画幅用 size （只决定竖 / 横 / 方，不决定清晰度）： 720x1280 (竖 9:16，默认) / 1280x720 (横 16:9) / 960x960 (方 1:1)；实际输出分别约 416×752 / 752×416 / 560×560 （均 480p 档，数字仅为画幅代号，不代表出 720p）。
- 参考图 ： image_url （公网 URL / base64 Data URI / 本地 @file 仅 multipart），字段名 image / images / reference_images / input_reference 亦兼容， 最多 7 张 ，multipart 每张 ≤ 5MB。
- 按次计费 ¥0.15/条、 失败不计费 ；令牌分组 xAI / auto ；客户端超时建议 ≥ 180 秒、轮询 3-5 秒。
```
# 文生视频（只给提示词，JSON body）
curl https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video-6s","prompt":"红色复古跑车在霓虹夜街疾驰，电影感","size":"1280x720"}'

# 图生视频（带参考图：image_url 为公网 URL 或 base64 Data URI）
curl https://YOUR_BASE/v1/videos \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video-6s","prompt":"人物轻轻转头微笑，柔光","image_url":"https://your-public-image.jpg","size":"720x1280"}'
```

---

# Grok 图像生成（文生图 / 图生图）
来源：https://docs.oairegbox.cc/#sec-grok-image

## Grok 图像生成（文生图 / 图生图）
OpenAI 兼容的 同步 图像接口，请求成功后直接返回图像、 无需轮询 。文生图三档质量任选；图生图 / 图片编辑用 grok-imagine-image 或 grok-imagine-image-2.0 打 /v1/images/edits 传参考图即可，同名同价、由接口区分。

### 用法总览（选场景 → 端点 + 模型）
| 场景 | 端点 | 模型 |
| 文生图 | POST /v1/images/generations | grok-imagine-image / -2.0 / -lite |
| 图生图 / 图片编辑 | POST /v1/images/edits （传参考图） | grok-imagine-image / grok-imagine-image-2.0 |
| -lite 图生图 / 编辑 | — | ❌ 不支持 ， -lite 仅文生图；图生图请用 grok-imagine-image 或 -2.0 |

### 画幅（ size / aspect_ratio · 按模型）
| 模型 | size 可选 | aspect_ratio 可选 | 默认 |
| grok-imagine-image | 1024x1024 / 1792x1024 / 1024x1792 | 1:1 / 16:9 / 9:16 / 2:3 / 3:2 / 4:3 / 3:4 | 1024x1024 |
| grok-imagine-image-2.0 | 1024x1024 / 1792x1024 / 1024x1792 / 2048x2048 （2K） | 同上 | 1024x1024 |
| grok-imagine-image-quality | 1024x1024 / 1792x1024 / 1024x1792 （ 仅 1K ） | 同上 | 1024x1024 |
| grok-imagine-image-lite | 1280x720 / 720x1280 / 960x960 | —（改用 size ） | — |

### 模型与价格
| 模型 | 能力 | 计费 | 价格 |
| grok-imagine-image-lite | 文生图（basic 档） | 按张 | ¥0.02/张 |
| grok-imagine-image | 文生图 + 图生图 / 编辑 | 按张 | ¥0.055/张 |
| grok-imagine-image-2.0 | 文生图 + 图生图 / 编辑（新版，质感更好，支持 2K） | 按张 | ¥0.065/张 |
| grok-imagine-image-quality | 文生图 + 图生图 / 编辑（质感档，仅 1K） | 按张 | ¥0.08/张 |

### 鉴权与分组
| 项 | 说明 |
| 鉴权 | Authorization: Bearer sk-xxx |
| 令牌分组 | xAI 或 auto （智能路由）分组均可 |
| 请求格式 | 文生图走 JSON；图生图 / 编辑走 JSON 或 multipart（传文件用 -F "image[]=@a.png" ） |

### 核心参数
| 参数 | 取值 | 默认 | 说明 |
| model | grok-imagine-image-lite / grok-imagine-image / grok-imagine-image-2.0 ；图生图 / 编辑用 grok-imagine-image 或 grok-imagine-image-2.0 （打 /v1/images/edits ）； -lite 仅文生图 | - | 必填 |
| prompt | 文本 | - | 必填，描述希望生成或修改的画面 |
| n | 整数 | 1 | 可选，生成数量；建议一次请求传 1 |
| response_format | url / b64_json | url | url 返回下载地址； b64_json 直接返回 Base64 图像数据 |
| size | 1024x1024 / 1792x1024 / 1024x1792 / 2048x2048 （ 2048x2048 仅 -2.0 ； -lite 见画幅说明） | 1024x1024 | 可选，输出尺寸； grok-imagine-image / -2.0 / -quality 适用 |
| resolution | 1k / 2k | 1k | 可选，仅 grok-imagine-image-2.0 支持 2k ；与 size 效果等价，二者皆可 |
| aspect_ratio | 1:1 / 16:9 / 9:16 / 2:3 / 3:2 / 4:3 / 3:4 | - | 可选， grok-imagine-image / -2.0 / -quality 用，与 size 二选一 |
| image | 公网 URL 或 base64 Data URI | - | 图生图可选，单张参考图。base64 必须为完整的 data:image/...;base64,... 格式 |
| images | URL / Data URI 数组 | - | 图生图可选，多张参考图；仅 JSON 请求使用 |

### 提交方式（传图 · 图生图）
| 方式 | 字段 / 写法 | 说明 |
| 单张公网图片 | "image": "https://.../a.jpg" | 图片地址必须能从公网直接访问 |
| 单张 base64 | "image": "data:image/png;base64,..." | 使用完整 Data URI，不要只传裸 Base64 |
| 多张 JSON 图片 | "images": ["https://.../a.jpg", "data:image/png;base64,..."] | 数组中可混用公网 URL 与 Data URI |
| multipart 文件上传 | -F "image[]=@a.png" -F "image[]=@b.jpg" | 单图也可使用 -F "image=@a.png" |

### 示例请求
```
# 文生图
curl https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-lite",
    "prompt": "一座漂浮在云海上的未来城市，清晨柔光，电影感",
    "n": 1,
    "response_format": "url"
  }'

# 图生图：JSON 单张公网图片
curl https://YOUR_BASE/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "保留主体构图，将背景改为雨后的霓虹街道",
    "image": "https://your-public-image.jpg",
    "response_format": "url"
  }'

# 图生图：multipart 多张文件
curl https://YOUR_BASE/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=grok-imagine-image" \
  -F "prompt=融合两张参考图的风格，生成商品展示图" \
  -F "image[]=@reference-a.png" \
  -F "image[]=@reference-b.jpg" \
  -F "response_format=url"
```

### 轮询取片（同步返回，无需轮询）
本模型为 同步接口 ：请求成功后 直接在响应里返回图像 ， 无需轮询 task_id 。返回结构如下：
```
{
  "created": 1786675686,
  "data": [
    {
      "url": "https://YOUR_BASE/v1/images/proxy/<encrypted-token>"
    }
  ]
}
```
response_format=url 时返回平台下载代理地址，浏览器或程序可直接访问；地址不暴露源站下载域名和签名参数，默认有效期 30 天。需要自行保存图片数据时用 response_format=b64_json 并读取 data[].b64_json 。

### Python 完整请求
```
import requests

BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 文生图（同步，直接拿结果）
r = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "grok-imagine-image-lite",
    "prompt": "一座漂浮在云海上的未来城市，清晨柔光，电影感",
    "n": 1,
    "response_format": "url"
}).json()
print("图片:", r["data"][0]["url"])

# 图生图：单张公网图片
r2 = requests.post(f"{BASE}/images/edits", headers=H, json={
    "model": "grok-imagine-image",
    "prompt": "保留主体构图，将背景改为雨后的霓虹街道",
    "image": "https://your-public-image.jpg",
    "response_format": "url"
}).json()
print("图片:", r2["data"][0]["url"])
```

### Python 示例：文生图 → 图生图（base64 参考图闭环）
先文生图拿到一张图，再把它当参考图做编辑——同一个 grok-imagine-image ，只换接口（ /generations → /edits ）；用 b64_json 免下载直接复用，参考图传完整的 data:image/...;base64, Data URI。
```
import requests, base64

BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 1) 文生图：生成一张参考图（取 b64_json，方便直接复用，无需下载）
gen = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "grok-imagine-image",
    "prompt": "一只黄色小鸭子，居中，纯白背景",
    "n": 1,
    "response_format": "b64_json",
}).json()
b64 = gen["data"][0]["b64_json"]
open("duck.jpg", "wb").write(base64.b64decode(b64))

# 2) 图生图 / 编辑：把上一步的图当参考图（完整 data URI），只加一顶圣诞帽、其余不变
edit = requests.post(f"{BASE}/images/edits", headers=H, json={
    "model": "grok-imagine-image",
    "prompt": "给鸭子头上戴一顶红色圣诞帽，保持同一只鸭子和纯白背景不变",
    "image": "data:image/jpeg;base64," + b64,
    "response_format": "b64_json",
}).json()
open("duck_hat.jpg", "wb").write(base64.b64decode(edit["data"][0]["b64_json"]))
print("done: duck.jpg -> duck_hat.jpg")
```

### 注意事项
- 接口为同步接口，请等待响应中的 data 返回后再处理结果。
- 参考图 公网 URL 必须能被服务端直接下载（含中国境内可访问） ，否则会失败或被忽略；需要登录、内网、访问受限或境外不可达的链接，请改用 base64 （ data:image/...;base64, ）内联。
- 使用 JSON 多图时传 images 数组；使用 multipart 多图时重复传 image[] 字段。
- url 与 b64_json 二选一：前者适合直接展示或下载，后者适合本地持久化或二次处理。

### 建议
- 一次请求出一张 ： n 建议传 1 ，需要多张分多次请求，稳定性更好。
- 直接展示用 url ，落库用 b64_json ：前者拿代理下载地址（30 天有效），后者拿 Base64 便于本地持久化。
- 图生图选清晰参考 ：参考图主体清晰、无遮挡，改风格 / 换背景类指令效果最稳。

---

# 通义万相 3.0 视频 Video
来源：https://docs.oairegbox.cc/#sec-wan

## 通义万相 3.0 视频 Video

### 模型与价格
| 模型 | 分辨率(resolution) | 计费 | 价格 |
| wan3.0-video | 480p（默认） | 按秒 | ¥0.21 / 秒 |
| wan3.0-video | 720p | 按秒 | ¥0.42 / 秒 |
| wan3.0-video | 1080p | 按秒 | ¥0.84 / 秒 |
| wan3.0-video-prime | 480p（默认） | 按秒 | ¥0.38 / 秒 |
| wan3.0-video-prime | 720p | 按秒 | ¥0.76 / 秒 |
| wan3.0-video-prime | 1080p | 按秒 | ¥1.52 / 秒 |

### 五大参考场景速查（ABCDE 模式总览）
| 模式 | 场景名称 | 核心能力 | 触发参数 / 字段写法 | 说明与适用业务 |
| A | 文生视频 | 纯文字创意生成 | 仅传 prompt ，不带任何素材 | 概念演示、光影特效、CG 场景想象 |
| B | 图生视频（首帧 / 首尾帧） | 单图动效 / 双图定格转场 | 传 1 张图片为首帧（ images 或 image_url ）； 或传 2 张图片分别指定 first_frame 与 last_frame | 静态立绘动效化、前后两张分镜之间精准平滑过渡 |
| C | 多图参考生视频 | 主体角色 / 场景一致性 | images 传入多张图片（≥3 张，或传 role: "reference_image" ） | 保持主体人物面容、服饰、环境特征与艺术风格连续统一 |
| D | 图 + 视频 + 音频多模态参考 | 跨模态运镜与节拍同步 | 同时组合 images + videos + audios | 角色参考图片，运镜与动作跟随参考视频，节奏与对白跟随参考音频 |
| E | 文件 / 网页链接参考 | 文档解析与网页推演 | 传入 files （文档 URL 数组）或 links （网页 URL 数组） | 研报/策划案/长文解析视频化、电商产品落地页一键生成推广视频 |

### 接口信息
| 项 | 说明 |
| Base URL | https://newapi-2.oairegbox.cc （或 https://api.oairegbox.cc ） |
| 提交端点 | POST /v1/video/generations 或 POST /v1/videos （标准 JSON，双端点完全等价兼容） |
| 轮询端点 | GET /v1/video/generations/{task_id} 或 GET /v1/videos/{task_id} |
| 成片下载 | 轮询状态为 completed 时，直接读取响应中的顶层 video_url （阿里云 OSS 官方高速直链，稳定且不脱敏）；亦支持通过网关端点 GET /v1/videos/{task_id}/content （带 Bearer 鉴权 302 重定向）流式下载 |
| 鉴权方式 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Wan （通义万相）或 auto （智能路由分组） |
| 生成耗时 | 通常 1–5 分钟（多模态与高分辨率耗时相应增加）；客户端请异步轮询取片，切勿在超时前重复发起同一任务 |

### 核心参数规范
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | wan3.0-video （全能多模态参考版）或 wan3.0-video-prime （优速版，30fps） |
| prompt | string | 是 | - | 画面内容、动态走势、光影氛围或镜头运动描述。走官方模型上下文，无我方硬性长度限制 |
| resolution | string | 否 | 480p | 决定清晰度与计费单价 ： 480p / 720p / 1080p （大小写兼容）。也可用 size 传 宽x高 （如 1280x720 ），系统自动匹配就近档位 |
| ratio | string | 否 | adaptive | 画幅比例 ： 16:9 （横屏）、 9:16 （竖屏）、 1:1 （方屏）、 4:3 、 3:4 、 adaptive （默认根据参考素材自适应）。兼容 portrait / landscape 等别名 |
| duration / seconds | integer / string | 否 | 5 | 视频生成时长（秒），支持 5–30 秒 。实际扣费以此秒数结算 |
| images | array | 否 | - | 参考图片列表 ：支持纯 URL 字符串数组或带角色对象数组 [{ "url": "...", "role": "..." }] 。单图默认首帧；双图默认首尾帧；3 张以上默认参考图。显式角色支持 first_frame （首帧）、 last_frame （尾帧）、 reference_image （参考图） |
| videos | array | 否 | - | 参考视频列表 ：纯 URL 字符串数组或 [{ "url": "...", "role": "reference_video" }] 。作为画面运动节奏与镜头轨迹的参考素材 |
| audios | array | 否 | - | 参考音频列表 ：纯 URL 字符串数组或 [{ "url": "...", "role": "reference_audio" }] 。⚠️ 不可作为唯一参考素材 ，至少需搭配一张图片或一段视频 |
| files | array | 否 | - | 参考文档列表 ：纯 URL 字符串数组或 [{ "url": "...", "role": "file" }] 。支持公网可直接下载的 PDF、Word、TXT、Markdown 等文档 |
| links | array | 否 | - | 参考网页列表 ：纯 URL 字符串数组或 [{ "url": "...", "role": "link" }] 。支持公网可抓取的 HTTP/HTTPS 网页，模型自动提取网页图文进行视频创作 |
| image_url | string | 否 | - | 单图快捷参数 ：传了=图生视频首帧。公网直链 URL 或完整 Base64 Data URI；兼容 image 、 input_reference |

### 全场景调用详解与示例（ABCDE 全覆盖）
通义万相 3.0 支持双端点（ /v1/video/generations 与 /v1/videos ）。以下示例均以标准 OpenAI 规范给出完整的 curl 请求与 Python 异步生命周期完整脚本。

#### 场景 A：文生视频（Text-to-Video）
只传文字描述，模型完全凭空渲染。支持自由指定分辨率（480p/720p/1080p）、画幅比例（16:9/9:16/1:1 等）与时长（5–30 秒）。

##### A-1. curl 示例（文生视频）
```
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "一只金毛寻回犬在金色秋叶中奔跑，电影感慢镜头，阳光穿透树林，毛发细节清晰",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
```

##### A-2. Python 完整示例（文生视频 · 提交 + 轮询 + 下载成片）
```
import time
import requests

BASE_URL = "https://YOUR_BASE"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交文生视频任务
payload = {
    "model": "wan3.0-video",
    "prompt": "浩瀚宇宙中的星际飞船正在穿越瑰丽的紫色星云，科幻史诗感，超高清光影",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
}
resp = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
print(f"[A. 文生视频] 任务已提交，Task ID: {task_id}")

# 2. 轮询任务状态直至完成
start_time = time.time()
video_url = None
while time.time() - start_time < 600:
    poll_resp = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30)
    poll_resp.raise_for_status()
    poll_data = poll_resp.json()
    status = poll_data.get("status")
    print(f"当前状态: {status} (已等待 {int(time.time() - start_time)}s)")
    if status == "completed":
        video_url = poll_data.get("video_url") or (poll_data.get("data") and poll_data["data"][0].get("url"))
        break
    elif status in ("failed", "canceled"):
        raise RuntimeError(f"任务生成失败: {poll_data.get('error')}")
    time.sleep(5)

# 3. 下载视频文件
if video_url:
    print(f"成片下载地址: {video_url}")
    video_content = requests.get(video_url, timeout=120).content
    with open("wan_scene_a.mp4", "wb") as f:
        f.write(video_content)
    print("成片已成功保存至本地 wan_scene_a.mp4")
```

#### 场景 B：图生视频（首帧 / 首尾帧）
包括 单图首帧动效 与 双图首尾帧过渡 ：
- 单图首帧 ：传入 1 张图片，模型以该图作为视频起始画面，随提示词运镜演绎；
- 双图首尾帧 ：传入两张图分别标注 first_frame 与 last_frame ，模型生成连接首尾两帧的自然运动轨迹。

##### B-1. curl 示例（单图首帧 & 双图首尾帧）
```
# ① 单图首帧动效（图片亦可传 base64）
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "微风吹拂，人物发丝轻扬，眼波流转，面带微笑",
    "image_url": "https://your-domain.com/start_frame.jpg",
    "resolution": "720p",
    "duration": 5
  }'

# ② 双图首尾帧平滑过渡（精准转场）
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "镜头由近景平滑拉远并旋转，画面由第一张日间场景自然过渡到第二张夜幕降临",
    "images": [
      { "url": "https://your-domain.com/day_view.jpg", "role": "first_frame" },
      { "url": "https://your-domain.com/night_view.jpg", "role": "last_frame" }
    ],
    "resolution": "720p",
    "duration": 5
  }'
```

##### B-2. Python 完整示例（双图首尾帧过渡）
```
import time
import requests

BASE_URL = "https://YOUR_BASE"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "wan3.0-video",
    "prompt": "镜头缓慢平移推进，人物由低头沉思自然抬起头并露出微笑",
    "images": [
        {"url": "https://your-domain.com/head_down.png", "role": "first_frame"},
        {"url": "https://your-domain.com/look_up_smile.png", "role": "last_frame"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
}

resp = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print(f"[B. 首尾帧图生视频] 任务已提交: {task_id}")

while True:
    res = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30).json()
    st = res.get("status")
    if st == "completed":
        video_url = res.get("video_url") or res["data"][0]["url"]
        with open("wan_scene_b_keyframes.mp4", "wb") as f:
            f.write(requests.get(video_url, timeout=120).content)
        print("首尾帧过渡视频下载完成！")
        break
    elif st in ("failed", "canceled"):
        raise RuntimeError(f"失败: {res.get('error')}")
    time.sleep(5)
```

#### 场景 C：多图参考生视频（Multi-Image Reference）
传入 3 张或更多参考图片（或显式指定 role: "reference_image" ），模型综合提取所有参考图中的主体角色、服装配饰与环境风格，生成风格高度统一的连续视频，解决 AI 视频人物脸部不一致的问题。

##### C-1. curl 示例（多图参考保持主体一致）
```
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "参考图片中的主角身着同一套战袍，在古代演武场上挥舞长剑，动作凌厉，保持脸部与服装一致",
    "images": [
      { "url": "https://your-domain.com/character_front.jpg", "role": "reference_image" },
      { "url": "https://your-domain.com/character_side.jpg", "role": "reference_image" },
      { "url": "https://your-domain.com/character_armor_detail.jpg", "role": "reference_image" }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
```

##### C-2. Python 完整示例（多图参考角色一致性）
```
import time
import requests

BASE_URL = "https://YOUR_BASE"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 传入多张不同角度/细节的主体图片
ref_images = [
    "https://your-domain.com/hero_angle_1.png",
    "https://your-domain.com/hero_angle_2.png",
    "https://your-domain.com/hero_close_up.png"
]

payload = {
    "model": "wan3.0-video",
    "prompt": "主角在繁华的赛博朋克夜市街道穿行，霓虹倒影，画面忠实再现参考图中的人物外貌与发型细节",
    "images": [{"url": u, "role": "reference_image"} for u in ref_images],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
}

r = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=60).json()
task_id = r["task_id"]
print(f"[C. 多图参考] 任务提交成功: {task_id}")

while True:
    data = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS).json()
    if data["status"] == "completed":
        url = data.get("video_url") or data["data"][0]["url"]
        with open("wan_scene_c_multiref.mp4", "wb") as f:
            f.write(requests.get(url, timeout=120).content)
        print("多图参考一致性视频已保存！")
        break
    elif data["status"] in ("failed", "canceled"):
        raise RuntimeError(data.get("error"))
    time.sleep(5)
```

#### 场景 D：图 + 视频 + 音频多模态参考（Multimodal Reference）
跨越单一维度的多模态协同创作：传入 角色主体图片 、 动作参考视频 与 节奏音频 。模型将结合参考视频的镜头运动与运镜轨迹、参考音频的节拍/情绪，并映射到参考图的角色身上，输出高精度的动作与视听协同成片。

##### D-1. curl 示例（图 + 视频 + 音频多模态）
```
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "让画面中的虚拟歌姬跟随参考视频的舞蹈动作起舞，动作节奏与参考音频的高潮卡点完全吻合",
    "images": [
      { "url": "https://your-domain.com/singer_character.png", "role": "reference_image" }
    ],
    "videos": [
      { "url": "https://your-domain.com/dance_motion_ref.mp4", "role": "reference_video" }
    ],
    "audios": [
      { "url": "https://your-domain.com/bgm_beat_ref.mp3", "role": "reference_audio" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'
```

##### D-2. Python 完整示例（图视音频全模态协同）
```
import time
import requests

BASE_URL = "https://YOUR_BASE"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 组装跨模态素材
payload = {
    "model": "wan3.0-video",
    "prompt": "角色身形与外貌严格参照图片，动作与运镜跟随参考视频，节奏与节拍跟随音频",
    "images": ["https://your-domain.com/actor_portrait.jpg"],
    "videos": ["https://your-domain.com/action_scene_ref.mp4"],
    "audios": ["https://your-domain.com/audio_tempo_ref.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
}

resp = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print(f"[D. 全模态协同] 任务已提交: {task_id}")

while True:
    status_resp = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS).json()
    st = status_resp.get("status")
    print(f"生成进度: {st}")
    if st == "completed":
        url = status_resp.get("video_url") or status_resp["data"][0]["url"]
        with open("wan_scene_d_multimodal.mp4", "wb") as f:
            f.write(requests.get(url, timeout=180).content)
        print("多模态视听联动视频生成完毕！")
        break
    elif st in ("failed", "canceled"):
        raise RuntimeError(status_resp.get("error"))
    time.sleep(6)
```

#### 场景 E：文件 / 网页链接参考（Doc & Link Reference）
支持将长文档（策划案、剧本、产品白皮书 PDF 等）或公开网页链接直接喂给模型。模型深度解析文档要点或网页的图文资产，生成专业的宣传解说、资讯播报或产品介绍视频。

##### E-1. curl 示例（文档 + 网页链接参考）
```
curl -sS -X POST "https://YOUR_BASE/v1/video/generations" \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "根据所附产品策划文档与官网产品落地页的内容，制作一段具有科技感的新品发布概念视频",
    "files": [
      { "url": "https://your-domain.com/product_brief.pdf", "role": "file" }
    ],
    "links": [
      { "url": "https://your-domain.com/product_landing_page", "role": "link" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'
```

##### E-2. Python 完整示例（文档与网页生视频）
```
import time
import requests

BASE_URL = "https://YOUR_BASE"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "wan3.0-video",
    "prompt": "结合文档剧本大纲与参考网页的视觉设计风格，生成一段电影宣发概念预告片",
    "files": ["https://your-domain.com/movie_synopsis.pdf"],
    "links": ["https://your-domain.com/official_movie_site"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
}

r = requests.post(f"{BASE_URL}/v1/video/generations", headers=HEADERS, json=payload, timeout=60).json()
task_id = r["task_id"]
print(f"[E. 文档/网页参考] 任务提交: {task_id}")

while True:
    data = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS).json()
    if data["status"] == "completed":
        url = data.get("video_url") or data["data"][0]["url"]
        with open("wan_scene_e_doc_link.mp4", "wb") as f:
            f.write(requests.get(url, timeout=120).content)
        print("文档/网页参考生成视频已下载！")
        break
    elif data["status"] in ("failed", "canceled"):
        raise RuntimeError(data.get("error"))
    time.sleep(5)
```

### 异步轮询取片与成片下载
通义万相 3.0 为纯异步生成接口。提交任务后返回唯一的 task_id ，客户端随后调用轮询接口查询任务状态：
```
# 查询任务状态（双端点兼容）
curl -sS "https://YOUR_BASE/v1/video/generations/task_xxx" \
  -H "Authorization: Bearer sk-xxx"

# 响应示例（已完成）：
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "completed",
  "progress": 100,
  "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=...",
  "data": [
    {
      "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=..."
    }
  ]
}
```
| 字段 | 说明 |
| status | 任务当前状态： queued （排队中）/ processing （渲染中）/ completed （已完成）/ failed （已失败） |
| video_url | 成片视频直链。为阿里云 OSS 官方下载直链（稳定不防盗链，可直接用于业务展示或存储分发） |
| data[0].url | 同 video_url ，OpenAI 规范格式 |

### 注意事项与最佳实践
- 按秒 × 分辨率精准计费 ：无论文生还是多模态参考，计费单价仅与分辨率档位及 duration 时长挂钩； 生成失败不扣费 。
- 分辨率名实相符 ：请求 720p 即出 720p，请求 1080p 即出真实 1080p 高清视频，底层绝不偷换低清降级。
- 模型版本选择 ： wan3.0-video ：全能版，多模态参考适应面最广，性价比极高； wan3.0-video-prime ：优速版，原生 30fps 流畅高帧率、运动画质更细腻且出片速度更快，适合对质感与效率有极高要求的商用场景。
- 素材访问要求 ：所有图片、视频、音频、文档、网页的 URL 必须能被公网直接 GET 访问（避免放在需登录或存在严格防盗链的私有云上）；图片支持 Base64 Data URI。
- 素材互斥守则 ：不要在单次请求中将首尾帧与视频/音频/文件/链接混合传入。
- 内容安全合规 ：提示词与所有多模态素材请遵守公序良俗，避免暴力、未成年、涉政等敏感内容，拦截任务不计费。

---

# 快手可灵 · Kling 3.0 / Kling-v3 官方直连 Video
来源：https://docs.oairegbox.cc/#sec-kling

## 快手可灵 · Kling 3.0 / Kling-v3 官方直连 Video

### 模型列表与计费说明（按秒计费 · 全默认有声）
本平台提供三档不同清晰度的固定模型（底层均完整具备多图融合与视频参考能力）：
| 模型名称 | 档位说明 | 分辨率 | 计费单价 | 适用场景 |
| kling-v3-standard | 标准版 | 720p | ¥0.765/秒 | 性价比首选，适合快速出片与日常生成 |
| kling-v3-pro | 专业版 | 1080p | ¥1.020/秒 | 高清写实，光影与细节更丰富 |
| kling-v3-4k | 4K 超清版 | 3840×2160 (4K) | ¥2.550/秒 | 影视级超高清成片输出 |

### 接口信息
| 项 | 说明 |
| 提交端点 | POST /v1/videos 或 POST /v1/video/generations （标准 JSON，双端点完全等价兼容） |
| 轮询端点 | GET /v1/videos/{task_id} 或 GET /v1/video/generations/{task_id} |
| 视频直出预览 | GET /v1/videos/{task_id}/content （带 Bearer 令牌鉴权 302 重定向流式返回成片） |
| 下载成片 | 完成后响应里的 data[0].url （官方腾讯 VOD 高速直链，稳定不过期） |
| 鉴权方式 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Kling （或 auto 智能路由分组） |

### 完整参数字典
| 参数名 | 类型 | 必填 | 默认值 | 详细说明与取值范围 |
| model | string | 是 | - | 模型名，如 kling-v3-standard 、 kling-v3-pro 或 kling-v3-4k |
| prompt | string | 是 | - | 画面动作描述，字数上限 2000 字符 |
| negative_prompt | string | 否 | - | 负向提示词，用于过滤低画质、多肢体、杂乱文字等不需要的元素 |
| duration / seconds | integer / string | 否 | 5 | 生成时长（秒），支持 5 或 10 （如 5 、 10 、 "5" 、 "10" ） |
| ratio / aspect_ratio | string | 否 | 16:9 | 视频画幅比例，支持 16:9 （横屏）、 9:16 （竖屏）、 1:1 （方形） |
| resolution | string | 否 | 依模型 | 视频清晰度，各模型已固定清晰度；亦可通过 resolution 或 size 显式指定 |
| images / image_urls | array | 否 | - | 参考图片链接数组或对象数组： • 传入 1 张图片：作为图生视频首帧； • 传入 2 张图片：第一张为 首帧 ，第二张为 尾帧 ，模型平滑过渡； • 传入对象数组：支持显式指定 role ，可选 first_frame （首帧）、 last_frame （尾帧）、 reference_image （参考图） |
| videos | array | 否 | - | （Omni 多模态专属） 参考视频链接数组，传入视频 URL 用于动作复刻或风格迁移 |
| generate_audio | boolean | 否 | true | 是否生成配套音效。本平台默认开启； 注：当请求包含参考视频时，模型限制暂不支持同时生成音频 |
| camera_control | object | 否 | - | 镜头运镜控制对象（包含 type: "simple" 或 "config" ），支持通过各项维度微调运镜动作： • pan ：水平平移（左右）； • tilt ：垂直俯仰（上下）； • zoom ：镜头变焦推拉； • roll ：镜头旋转 |

### 调用代码示例

#### A. 经典文生视频（Text-to-Video）
```
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro",
    "prompt": "繁华都市霓虹灯下的雨夜，一个打着雨伞的行人在积水的路面上缓慢行走，写实电影风格，光影斑驳",
    "negative_prompt": "画面模糊，低画质，崩坏肢体，水印",
    "ratio": "16:9",
    "duration": 5
  }'
```

#### B. 经典图生视频（首尾帧控制）
传入 2 张图片链接：第一张自动作为首帧、第二张作为尾帧，由模型生成过渡画面。
```
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro",
    "prompt": "画面由第一张图片的人物微笑平滑过渡到第二张图片的惊讶表情，动作写实自然",
    "images": [
      "https://example.com/smile_face.png",
      "https://example.com/surprised_face.png"
    ],
    "duration": 5
  }'
```

#### C. 多图融合参考（Omni 特性）
支持传入多张参考图，通过对象指定 role （如角色外观首帧 + 场景风格参考图）。
```
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro",
    "prompt": "参考图片一中的女主角和图片二的复古咖啡馆场景，绘制一段平稳摇臂运镜的画面",
    "images": [
      {
        "url": "https://example.com/character.png",
        "role": "first_frame"
      },
      {
        "url": "https://example.com/coffee_shop.png",
        "role": "reference_image"
      }
    ],
    "resolution": "1080p",
    "duration": 5
  }'
```

#### D. 图像参考 + 视频参考多模态混合生成（动作/运镜复刻）
可同时传入参考图与参考视频，实现人物外观由图片决定、主体招式动作与镜头由视频决定的混合生成。
```
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-pro",
    "prompt": "图一中的人物作为主角，完美复刻视频中的武术动作，动作流畅，画风高清写实",
    "images": [
      {
        "url": "https://example.com/my_character.png",
        "role": "reference_image"
      }
    ],
    "videos": [
      "https://example.com/motion_reference.mp4"
    ],
    "resolution": "1080p",
    "duration": 5
  }'
```

### 轮询结果响应格式
查询请求（支持双端点）：
```
curl -X GET https://api.oairegbox.cc/v1/videos/你的任务ID \
  -H "Authorization: Bearer sk-你的令牌"
```
任务完成响应示例（200 OK）：
```
{
  "id": "task_zbpGfYv1qStMwLwVtPW8G59KOGfDJr9k",
  "status": "completed",
  "object": "video.generation",
  "data": [
    {
      "url": "https://gpt2api.oairegbox.cc/d/kling/1251015623-AigcVideoTask-ecdc586e9cf2b2419844a1309e3b3691t"
    }
  ]
}
```

### Python 完整请求示例（全生命周期）
```
import time
import requests

BASE_URL = "https://api.oairegbox.cc"
API_KEY = "sk-你的令牌"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交视频生成任务
payload = {
    "model": "kling-v3-pro",
    "prompt": "繁华都市霓虹灯下的雨夜，一个打着雨伞的行人在积水的路面上缓慢行走，写实电影风格，光影斑驳",
    "negative_prompt": "画面模糊，低画质，崩坏肢体，水印",
    "ratio": "16:9",
    "duration": 5
}
resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"任务已提交，Task ID: {task_id}")

# 2. 轮询直到生成完成
start_time = time.time()
while time.time() - start_time < 900:
    poll_res = requests.get(f"{BASE_URL}/v1/videos/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll_res.get("status")
    print(f"当前状态: {status} (耗时: {int(time.time() - start_time)}s)")
    if status == "completed":
        video_url = poll_res["data"][0]["url"]
        # 3. 下载保存视频
        content = requests.get(video_url, timeout=120).content
        with open("kling_output.mp4", "wb") as f:
            f.write(content)
        print("视频已成功下载至本地 kling_output.mp4！")
        break
    elif status in ("failed", "canceled"):
        raise RuntimeError(f"任务失败: {poll_res.get('error')}")
    time.sleep(5)
```

### 注意事项
- 按秒计费规则 ：任务费用 = 实际出片秒数 × 档位每秒单价；失败或审核拦截不计费。
- 成片默认自带音频 ：标准版与专业版成片默认自带生成音效与 AAC 原生音轨；⚠️ 当请求包含参考视频（video reference）时，受官方规则限制：视频参考模式与音频生成互斥，平台将自动关闭音频生成 ，无需客户端额外排查。
- 双端点全面兼容 ：支持 POST /v1/videos 与 POST /v1/video/generations 提交，支持 /content 视频直出预览。
- 素材公网可访问 ：参考图片和参考视频 URL 必须能被公网直接访问下载。

---

# Flow · Omni 1.2 / 1.1 Flash Video
来源：https://docs.oairegbox.cc/#sec-flow-omni

## Flow · Omni 1.2 / 1.1 Flash Video

### 一、Flow · Omni 1.2 / 1.1 模型总览与价格对比
| 对客模型名称 ( model ) | 所属分组 | 支持玩法 | 分辨率 | 支持时长 ( seconds ) | 计费模式 | 对客单价 |
| flow-omni-1.2-flash 主力推荐 | Gemini flow （ gemini-flow-1 / auto ） | 文生 (T2V) / 首帧 (I2V) / 首尾帧 (2图) / 多参考图 (R2V 1~7图) | 720p（默认）/ 360p | "3" ~ "15" 任意整数秒（默认 "5" ） | 按秒计费 ( per_second ) | ¥0.11 / 秒 3s=¥0.33 · 5s=¥0.55 · 8s=¥0.88 · 10s=¥1.10 · 15s=¥1.65 |
| flow-omni-1.1-flash | Gemini flow （ gemini-flow-1 / auto ） | 文生视频 / 多图参考图生视频 | 720p | "4" / "6" / "8" （默认）/ "10" | 按次计费 | ¥0.75 / 次 （四档时长同价） |
| flow-omni-1.1-flash （v2v） | Gemini flow （ gemini-flow-1 / auto ） | 视频编辑（传参考视频 input_reference ，含图 + 视频同时参考） | 720p | "4" / "6" / "8" （默认）/ "10" | 按次计费 | ¥0.90 / 次 （四档时长同价） |

### 二、主力模型： flow-omni-1.2-flash （按秒计费 ¥0.11/秒）

#### 1. 模型基础与计费信息
| 配置项 | 对客参数值 / 说明 |
| 对客模型名称 ( model ) | flow-omni-1.2-flash |
| 所属分组 ( group ) | Gemini flow （内部 key： gemini-flow-1 ，已纳入 auto 自动分组，使用 auto 或 Gemini flow 分组令牌均可直接调用） |
| 计费模式 ( billing_mode ) | 按秒计费（ per_second ），失败不计费 |
| 对客单价 ( model_price ) | ¥0.11 / 秒 （全分辨率、全图生/文生玩法同价一口价）： • 3 秒 = ¥0.33 • 5 秒（默认） = ¥0.55 • 8 秒 = ¥0.88 • 10 秒 = ¥1.10 • 15 秒 = ¥1.65 |
| 支持时长 ( seconds ) | 支持 "3" ~ "15" 之间的任意整数字符串（如 "3" , "5" , "8" , "10" , "12" , "15" ）；未传时默认按 "5" 秒生成（ 重要提示：建议在请求体中始终显式传入 "seconds": "5" ~ "15" ） |
| 支持分辨率 ( size / aspect_ratio ) | • 720p（默认） ： 1280x720 （16:9 横屏，缺省默认）、 720x1280 （9:16 竖屏） • 360p ： 640x360 （16:9 横屏）、 360x640 （9:16 竖屏） • 或直接传 aspect_ratio ： "16:9" / "9:16" |

#### 2. 协议端点（标准 OpenAI Videos 异步视频协议）
与站内 flow-omni-1.1-flash / flow-veo-3-1 完全一致，共 3 个端点（双入口域名 https://api.oairegbox.cc 或 https://newapi.oairegbox.cc ）：
- 提交视频生成任务 ： POST /v1/videos （支持 application/json 与 multipart/form-data ）
- 轮询任务状态与进度 ： GET /v1/videos/{task_id} （状态流转： queued → in_progress → completed / failed ）
- 拉取 MP4 成片文件流 ： GET /v1/videos/{task_id}/content （ status="completed" 后调用，直接返回 Content-Type: video/mp4 二进制流；也可使用轮询响应中的顶层 video_url 下载）

#### 3. 支持的 4 种生成玩法（同一定价 ¥0.11/秒）
| 玩法模式 | input_reference 传参规则 | image_mode 参数 | 计费单价 |
| 1. 文生视频 (T2V) | 不传 input_reference | 不传 | ¥0.11 / 秒 |
| 2. 首帧图生视频 (I2V) | 传 1 张图（支持公网图片 URL、 data:image/...;base64,... 或 multipart/form-data 文件） | 不传（默认 "frames" ） | ¥0.11 / 秒 |
| 3. 首尾帧过渡 (First-Last) | 传 2 张图（JSON 数组 [首帧, 尾帧] ，或 multipart/form-data 传 2 个同名 input_reference 字段） | 不传（默认 "frames" ） | ¥0.11 / 秒 |
| 4. 多参考图遵循 (R2V) | 传 1 ~ 7 张参考图（JSON 数组或 multipart/form-data 多个 input_reference 字段） | 必传 "reference" | ¥0.11 / 秒 |

#### 4. flow-omni-1.2-flash 请求参数一览表
| 参数名 | 类型 | 必填 | 说明 |
| model | string | 是 | 固定传 "flow-omni-1.2-flash" |
| prompt | string | 是 | 视频画面与动作描述提示词 |
| seconds | string | 推荐必填 | 视频时长秒数（ 字符串 ），支持 "3" ~ "15" 任意整数秒（如 "5" , "8" , "10" , "15" ）；不传默认按 "5" 秒生成 |
| size | string | 否 | 分辨率尺寸： "1280x720" （默认 720p 横屏）、 "720x1280" （720p 竖屏）、 "640x360" （360p 横屏）、 "360x640" （360p 竖屏） |
| aspect_ratio | string | 否 | 画幅比例： "16:9" 或 "9:16" （与 size 二选一即可） |
| input_reference | string / string[] / file | 否 | 参考图输入：支持单张字符串、多张字符串数组（URL 或 Base64 Data URI），或 multipart/form-data 文件字段 |
| image_mode | string | 否 | 图片作用模式： "frames" （默认，最多 2 张作首帧/尾帧）或 "reference" （最多 7 张作多参考图 R2V） |

#### 5. flow-omni-1.2-flash 标准调用示例

##### ① 文生视频（T2V · JSON 方式）
```
curl -X POST "https://api.oairegbox.cc/v1/videos"   -H "Authorization: Bearer $OAIREGBOX_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "flow-omni-1.2-flash",
    "prompt": "A cute golden retriever puppy running happily on a sunny green lawn, cinematic lighting",
    "seconds": "5",
    "size": "1280x720"
  }'
```

##### ② 首尾帧过渡（First-Last · 传 2 张图）
```
curl -X POST "https://api.oairegbox.cc/v1/videos"   -H "Authorization: Bearer $OAIREGBOX_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "flow-omni-1.2-flash",
    "prompt": "Smooth camera transition from day to starry night over the mountain cabin",
    "seconds": "8",
    "size": "1280x720",
    "input_reference": [
      "https://example.com/start_frame.jpg",
      "https://example.com/end_frame.jpg"
    ]
  }'
```

##### ③ 多参考图遵循（R2V · 1~7 张图 + image_mode="reference" ）
```
curl -X POST "https://api.oairegbox.cc/v1/videos"   -H "Authorization: Bearer $OAIREGBOX_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "flow-omni-1.2-flash",
    "prompt": "The character from reference image 1 wearing the jacket from image 2, walking through the neon street in image 3",
    "seconds": "10",
    "size": "1280x720",
    "image_mode": "reference",
    "input_reference": [
      "https://example.com/char.png",
      "https://example.com/jacket.png",
      "https://example.com/street.png"
    ]
  }'
```

##### ④ 查询任务状态与下载 MP4 成片
```
# 1) 轮询任务状态
curl -s "https://api.oairegbox.cc/v1/videos/task_nAk9PZMTa1yAT5NjU1QHIr0LYbfMlT0w"   -H "Authorization: Bearer $OAIREGBOX_API_KEY"
# 返回示例：
# {
#   "id": "task_nAk9PZMTa1yAT5NjU1QHIr0LYbfMlT0w",
#   "object": "video",
#   "model": "omni-1.2-flash",
#   "status": "completed",
#   "progress": 100,
#   "seconds": "5",
#   "size": "1280x720",
#   "created_at": 1793985442,
#   "completed_at": 1793985512,
#   "error": null
# }

# 2) 当 status == "completed" 时，直接拉取 MP4 视频文件
curl -L "https://api.oairegbox.cc/v1/videos/task_nAk9PZMTa1yAT5NjU1QHIr0LYbfMlT0w/content"   -H "Authorization: Bearer $OAIREGBOX_API_KEY"   -o output.mp4
```

### 三、存量模型： flow-omni-1.1-flash （按次计费 ¥0.75 / 视频编辑 V2V ¥0.90）

### 三种模式（按素材自动切换）
| 模式 | 怎么触发 | 价格 / 次 | 说明 |
| 文生视频（T2V） | 只传 prompt ，不带图 / 视频 | ¥0.75 | 纯文字生成视频 |
| 图生视频（I2V） | prompt + images （或单张 image ） | ¥0.75 | 多图参考图生视频 |
| 视频编辑（V2V） | prompt + input_reference （参考视频） | ¥0.90 | 在原视频基础上按 prompt 编辑（如加特效 / 改天气 / 换风格）；参考视频 ≤15 秒 ，可传 base64 （本站自动托管）或 公网 URL （须中国可访问） |

### 接口信息
| 项 | 说明 |
| Base URL | https://api.oairegbox.cc |
| 提交任务 | POST /v1/videos （JSON） |
| 轮询进度 | GET /v1/videos/{task_id} ， status=completed 表示完成 |
| 下载成片 | 用轮询返回的顶层 video_url 直接下载 mp4（地址已脱敏、我方域名） |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Gemini flow |
| 耗时 | 通常 1–2 分钟；客户端应轮询，不要重复提交同一任务 |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 固定 flow-omni-1.1-flash （文生 / 图生 / 视频编辑都用这一个名字） |
| prompt | string | 是 | - | 画面 / 运动描述 |
| resolution | string | 否 | 720p | 固定 720p （本模型仅提供 720p） |
| aspect_ratio | string | 否 | 16:9 | 决定画幅 / 朝向 ： 16:9 （横屏，默认）/ 9:16 （竖屏）。 不传即横屏 ，要竖屏传 9:16 |
| size | string | 否 | - | 也可用 WxH 指定朝向（如 1280x720 横 / 720x1280 竖）；传了 size 时以它为准。清晰度恒 720p |
| seconds | string（ 必须字符串 ） | 否 | "8" | 成片时长（秒） ：可选 "4" / "6" / "8" / "10" ， 四档同价 。 必须传字符串 ——写成数字 10 会报 invalid_json ； 请用 seconds ， duration 不生效 ；传档位以外的值（如 "7" ）按 8 秒 出片、不报错 |
| images | 数组(URL / base64) | 否 | - | 图生视频 ：多图参考（ 建议 ≤6 张 ，多传模型可能只取前几张、不提升效果）；公网可直取 URL 或 data:image/...;base64, 。单张也可用 image |
| input_reference | string（URL 或 base64） | 否（v2v 必填） | - | 仅视频编辑（v2v）用 ：文生 / 图生视频 无需 此字段； 做 v2v 时必填 ——参考视频，可传 公网 URL （ ≤15 秒 、须 中国可访问 ）或 base64 （ data:video/mp4;base64, 或裸 base64；本站自动托管为中国可达链接，无需自己找公网地址；mp4/mov、解码后 ≤64MB）；传了即进入编辑模式，按 prompt 在原视频上编辑 |

#### 时长档位（实测对照 · 务必只传这四个值）
| 传 seconds | 实际成片时长 | 帧数（24fps） | 说明 |
| "4" | 4.0 秒 | 96 | 正常 |
| "6" | 6.0 秒 | 144 | 正常 |
| "8" 或 不传 | 8.0 秒 | 192 | 默认档 |
| "10" | 10.0 秒 | 240 | 正常 |
| 四档以外的值 （如 "7" 、 "15" ） | 8.0 秒 | 192 | ⚠️ 不报错、静默按 8 秒出片 ——你以为拿到 7 秒，实际是 8 秒 |
| 数字 10 （ 没加引号 ） | — | — | 请求 直接被拒 ： 400 invalid_json |
| duration 字段 | 8.0 秒 | — | 该字段 不生效 ，等同没传时长 |

#### 画幅与朝向（横屏 / 竖屏怎么定）
| 想要 | 用 aspect_ratio | 或用 size | 输出（恒 720p） |
| 横屏（默认） | 不传 或 "16:9" | "1280x720" | 1280 × 720 |
| 竖屏 | "9:16" | "720x1280" （或 "1080x1920" ） | 720 × 1280 |

### 示例请求（curl）
```
BASE_URL="https://api.oairegbox.cc"
TOKEN="sk-你的令牌"

# 1) 文生视频（720p 横屏，默认）
# seconds 可选 "4"/"6"/"8"/"10"（字符串），不传默认 8 秒，四档同价
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"flow-omni-1.1-flash","prompt":"日出时分平静的湖面雾气升腾，电影感镜头","seconds":"10"}'

# 2) 文生视频（竖屏 9:16）
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"flow-omni-1.1-flash","prompt":"竖屏短视频：城市夜景延时，霓虹流光","aspect_ratio":"9:16"}'

# 3) 图生视频（参考图，URL 或 base64）
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"flow-omni-1.1-flash","prompt":"参考这些图片生成连贯运镜","images":["https://img1.jpg","https://img2.jpg"]}'

# 4) 视频编辑 v2v（传参考视频 input_reference：公网 URL 或 base64 data-uri，≤15 秒）
curl -sS -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"flow-omni-1.1-flash","prompt":"给这段视频加上飘雪，保持原画面","input_reference":"https://your-public-video.mp4"}'
# 或把参考视频转 base64（本站自动托管为中国可达链接，无需公网地址）：把 input_reference 换成 "data:video/mp4;base64,<BASE64>"
# => {"task_id":"task_xxx","status":"queued",...}
```

### Python 完整示例（提交 → 轮询 → 下载）
```
import time, requests

BASE = "https://api.oairegbox.cc"
TOKEN = "sk-你的令牌"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# 提交：文生 720p 横屏。
#   竖屏 -> 加 "aspect_ratio": "9:16"
#   图生 -> 加 "images": ["https://.../a.jpg", "https://.../b.jpg"]（也支持 base64）
#   视频编辑 -> 加 "input_reference": "https://.../clip.mp4"（也支持 base64: data:video/mp4;base64,）  # 参考视频 ≤15s
payload = {
    "model": "flow-omni-1.1-flash",
    "prompt": "日出时分平静的湖面雾气升腾，电影感镜头",
    "aspect_ratio": "16:9",     # 16:9 横屏 / 9:16 竖屏
}
r = requests.post(f"{BASE}/v1/videos", headers=H, json=payload, timeout=60)
r.raise_for_status()
task = r.json()
task_id = task.get("task_id") or task.get("id")
print("task_id:", task_id)

# 轮询直到完成（通常 1-2 分钟，与时长档位无关）
while True:
    time.sleep(5)
    d = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H, timeout=30).json()
    status = str(d.get("status", "")).lower()
    print("status:", status, d.get("progress"))
    if status == "completed":
        video_url = d.get("video_url") or (d.get("data") or [{}])[0].get("url")
        print("成片:", video_url)
        break
    if status == "failed":
        raise RuntimeError(d.get("error") or d)

# 下载成片：用轮询返回的 video_url（地址已脱敏、我方域名）
mp4 = requests.get(video_url, timeout=180)
open("out.mp4", "wb").write(mp4.content)
print("已保存 out.mp4")
```

### Python 示例：图 + 视频同时参考（全能模式）
flow-omni-1.1-flash 支持 同时 传参考视频（ input_reference ，1 段）+ 参考图（ images ，可多张）。⚠️ images 必须是数组 ["u1","u2"] ， 不要写成 images0 / images1 （部分客户端会把数组拆成索引键，导致参考图不生效）。参考视频 只支持 1 段 ；参考图 建议 ≤6 张 。带参考视频即按 视频编辑（v2v）¥0.90 / 次 计费。
```
import time, base64, requests

BASE = "https://api.oairegbox.cc"
TOKEN = "sk-你的令牌"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

def data_url(path, mime):            # 本地文件转 base64 data-uri（可选）
    b64 = base64.b64encode(open(path, "rb").read()).decode()
    return f"data:{mime};base64,{b64}"

# 全能模式：参考视频（input_reference，1 段） + 参考图（images，可多张）同时用。
# ⚠ images 必须是【数组】["u1","u2"]，不要写成 images0 / images1（会导致参考图不生效）。
payload = {
    "model": "flow-omni-1.1-flash",
    "prompt": "参考这段视频的运动，把主体换成参考图里的形象，平滑运镜，电影感",
    "aspect_ratio": "16:9",
    "seconds": "10",            # "4"/"6"/"8"/"10"，字符串；不传默认 8 秒，四档同价
    # 参考视频：1 段，公网 URL（≤15 秒、中国可访问）或 base64（本站自动托管）
    "input_reference": "https://你的公网视频.mp4",   # 或 data_url("clip.mp4", "video/mp4")
    # 参考图：数组，建议 ≤6 张；URL 或 base64
    "images": [
        "https://你的图1.jpg",
        data_url("图2.png", "image/png"),
    ],
}

r = requests.post(f"{BASE}/v1/videos", headers=H, json=payload, timeout=60)
r.raise_for_status()
task_id = r.json().get("task_id") or r.json().get("id")
print("task_id:", task_id)

while True:                          # 轮询直到完成（通常 1-2 分钟，与时长档位无关）
    time.sleep(5)
    d = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H, timeout=30).json()
    print("status:", d.get("status"), d.get("progress"))
    if str(d.get("status", "")).lower() == "completed":
        video_url = d.get("video_url") or (d.get("data") or [{}])[0].get("url")
        break
    if str(d.get("status", "")).lower() == "failed":
        raise RuntimeError(d.get("error") or d)

open("out.mp4", "wb").write(requests.get(video_url, timeout=180).content)
print("成片:", video_url)
```

### 轮询取片
```
# 轮询直到 status=completed
curl -sS "$BASE_URL/v1/videos/task_xxx" -H "Authorization: Bearer $TOKEN"
# => {"status":"completed","video_url":"https://sd.oaibox.xyz/d/dl/xxx.mp4",...}

# 下载成片：用上面返回的 video_url（mp4，地址已脱敏、我方域名）
curl -sSL "<上面返回的 video_url>" -o out.mp4
```
轮询间隔建议 3–5 秒、客户端超时 ≥ 300 秒；勿重复提交同一任务。

### 注意事项
- 一个模型名 flow-omni-1.1-flash 、自动切换 ：带参考视频（ input_reference ）= 视频编辑；带参考图（ images ）= 图生视频；不带 = 文生视频。文生 / 图生 ¥0.75 / 次，视频编辑（v2v）¥0.90 / 次。
- 朝向用 aspect_ratio （ 16:9 横屏默认 / 9:16 竖屏），也可用 size 的 WxH ；清晰度恒 720p 。
- 比例非必填 ：不传默认横屏 16:9； 要竖屏传 aspect_ratio:"9:16" 。
- 无水印、时长 4 / 6 / 8 / 10 秒可选（默认 8 秒、四档同价） ； 文生 / 图生 ¥0.75 / 次、视频编辑（v2v）¥0.90 / 次 ； 按次计费、失败不计费 。
- ⚠️ 时长只传 "4" / "6" / "8" / "10" （字符串） ：传四档以外的值 不会报错 ，会 静默按 8 秒 出片；写成数字（没加引号）会报 invalid_json 。时长要紧的场景请核验成片实际时长，见上方「 时长档位 」一节。
- 多图参考 images ：参考图须 公网可直接下载 或用 base64 （需登录 / 内网 / 拦爬虫的链接会失败）。
- 视频编辑 input_reference ：参考视频 ≤15 秒 。可传 base64 （ data:video/mp4;base64, 或裸 base64；本站自动托管为中国可达链接，mp4/mov、解码后 ≤64MB）或 公网 URL （须中国可直接下载；国外 / 需登录的 URL 会取不到→退化为文生）。
- 生成约 1–2 分钟；轮询取片、勿重复提交同一任务。
- 提示词与参考图 / 视频避免暴露 / 未成年 / 血腥暴力等敏感内容，否则被内容安全拦截（不计费）。

---

# Gemini 高速文本模型
来源：https://docs.oairegbox.cc/#sec-gemini-text

## Gemini 高速文本模型
高速分组的文本 / 多模态对话模型，与 Official 分组的官方标准模型名和价格完全隔离。OpenAI Chat 兼容，同时支持 Gemini 原生格式。

### 模型与价格

#### 统一网关（令牌分组 gemini-fast / gemini-anti-ultra / gemini-vertex ）
| 模型 | 能力 | 多模态附件 | 计费 |
| gemini-4-argon-app | 旗舰高速版，1M 上下文 / 复杂推理 / 思维链（不支持工具调用） | ✅ 图 / 视频 / 音频 | 按 token（ gemini-fast 入 ¥0.56/M · 出 ¥2.8/M；如需工具调用请用 gemini-anti-ultra 的 gemini-4-argon ） |
| gemini-3.8-flash-app | 当前主力高速文本，最省 | ✅ 图 / 视频 / 音频 | 按 token |
| gemini-3.5-flash | 高速文本，综合能力更强 | ✅ 图 / 视频 / 音频 | 按 token |
| gemini-3.1-pro | Pro 档，长文 / 复杂推理 | ✅ 图 / 视频 / 音频 | 按 token |
| gemini-3.1-flash-lite | 轻量高速 | ✅ 图 / 视频 / 音频 | 按 token |
| gemini-3.5-flash-lite | 轻量高速（新版） | ✅ 图 / 视频 / 音频 | 按 token |
| gemini-2.0-flash-thinking | 思维链档，最省 | ✅ 图 / 视频 / 音频 | 按 token |

#### gemini-4-argon 多分组差异化定价说明
| 分组代号 | 分组展示名 | 模型名 | 分组倍率 | 输入单价 | 输出单价 | 缓存单价 | 定位说明 |
| gemini-anti-ultra | Gemini Antigravity Ultra | gemini-4-argon | 1.0 | ¥2/M （¥2.00/M） | ¥10/M （¥10.00/M） | ¥0.2/M | 反重力 Ultra 独立号池专线（官方基准 2/10 无折扣，高稳主力，已纳入 auto 链） |
| gemini-vertex | Gemini Vertex | gemini-4-argon | 1.8 | ¥3.6/M | ¥18/M | ¥0.36/M | Google Vertex AI 官方企业级通道（详见「Google Vertex / 官方原生」章节） |
| gemini-fast | Gemini Fast | gemini-4-argon-app | 1.0 | ¥0.56/M | ¥2.8/M | ¥0.056/M | 高性价比快速通道（纯对话/图文，不支持工具调用） |

### 接口信息
| 项 | 说明 |
| 请求 | POST https://api.oairegbox.cc/v1/chat/completions （OpenAI 兼容，同步； stream:true 可流式） POST https://api.oairegbox.cc/v1beta/models/gemini-4-argon:generateContent （Gemini 原生格式；流式用 :streamGenerateContent ） |
| 鉴权 | OpenAI 格式用 Authorization: Bearer sk-你的令牌 ；Gemini 原生格式用 x-goog-api-key: sk-你的令牌 |
| 令牌分组 | gemini-fast （高性价比快速通道） / gemini-anti-ultra （反重力 Ultra 独立专线， auto 自动分组已包含） / gemini-vertex （Google Vertex AI 通道） |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 见上表模型名；统一网关不加 -fast 后缀 |
| messages | array | 是 | - | OpenAI 消息数组； content 可含图片实现多模态 |
| stream | bool | 否 | false | 是否流式返回 |
| temperature | number | 否 | - | 采样温度 |
| max_tokens | int | 否 | - | 最大输出 token |

### 提交方式
标准 OpenAI Chat JSON。可直接用 OpenAI SDK：把 base_url 指向网关、 api_key 用你的令牌即可。

### 示例请求
```
# 基础对话（非流式）
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

# 流式输出（stream: true，SSE 实时打字效果）
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [
      {"role": "user", "content": "用三点总结人工智能的发展趋势"}
    ],
    "stream": true
  }'

# 多模态图文对话（图片传公网 URL 或 base64 Data URI）
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "描述这张图片中的主体内容"},
          {"type": "image_url", "image_url": {"url": "https://your-public-image.jpg"}}
        ]
      }
    ]
  }'

# Gemini 原生格式（非流式）
curl "https://YOUR_BASE/v1beta/models/gemini-4-argon:generateContent" \
  -H "x-goog-api-key: sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"parts": [{"text": "用一句话介绍你自己"}]}
    ]
  }'
```

### 多模态附件（图片 / 视频反推 / 音频）
在 messages[].content 里挂附件即可。 附件由平台自动下载并转交给模型 ，你只要给一个公网可访问的 URL（或 base64），不需要自己转存。典型用途是 视频反推 ：丢一段片子进去，让模型描述画面、还原分镜或倒推提示词。

#### 支持的写法
| 类型 | 写法 | 取值 |
| 图片 | {"type":"image_url","image_url":{"url":"…"}} 也接受 "image_url":"…" 直接给字符串 | 公网 URL / data:image/…;base64, / 裸 base64 |
| 视频 | {"type":"video_url","video_url":"…"} 也接受 "video_url":{"url":"…"} 对象形式 | 公网 URL / data:video/mp4;base64, / 裸 base64 |
| 音频 | {"type":"input_audio","input_audio":{"data":"<base64>","format":"mp3"}} 也接受 {"type":"audio_url","audio_url":"…"} | base64 或公网 URL |

#### 限制
| 项 | 限制 | 超限表现 |
| 单个附件大小 | 12MB | 返回 400，附带实际大小 |
| 视频 / 音频时长 | 180 秒 | 返回 400，附带实际时长 |
| 附件数量 | 不限，但合计仍受上面两条约束 | — |
| 历史轮次 | 只有 role: "user" 的轮次会上传附件 | 助手轮里的 URL 会被忽略，不重复计费 |

#### 计费：附件按实际体量计入 prompt_tokens
与 Google 官方多模态计量口径一致， 图片按实际像素分块、视频与音频按实际时长 ，不是固定一口价。返回的 usage 就是实际扣费依据（流式模式下随 [DONE] 前最后一个 chunk 返回）。
| 类型 | 计量规则 | 示例 |
| 图片 | 两边都 ≤384px 记 258 token；更大则按分块计，块边长 = 短边 ÷ 1.5（限制在 256–768），每块 258 token | 1024×1024 → 4 块 = 1032 4000×3000 → 24 块 = 6192 |
| 视频 | 263 token / 秒 （含音轨） | 30s → 7890 60s → 15780 180s → 47340 |
| 音频 | 32 token / 秒 | 60s → 1920 |

#### 示例：视频反推
```
# 传公网 URL，平台会自动下载并转交给模型
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "逐镜头描述这段视频：画面内容、镜头运动、节奏，并倒推出一段可以复现它的提示词"},
          {"type": "video_url", "video_url": "https://your-cdn.com/clip.mp4"}
        ]
      }
    ]
  }'

# 传 base64（无公网 URL 时）
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "这个视频里出现了什么文字？"},
          {"type": "video_url", "video_url": "data:video/mp4;base64,AAAAGGZ0eXBpc29t..."}
        ]
      }
    ]
  }'
```

#### 示例：图片理解 / 音频
```
# 图片
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [{"role":"user","content":[
      {"type":"text","text":"这张图里的文字是什么？"},
      {"type":"image_url","image_url":{"url":"https://your-public-image.jpg"}}
    ]}]
  }'

# 音频
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-app",
    "messages": [{"role":"user","content":[
      {"type":"text","text":"把这段音频转写成文字"},
      {"type":"input_audio","input_audio":{"data":"<BASE64>","format":"mp3"}}
    ]}]
  }'
```

#### Python（OpenAI SDK）
```
from openai import OpenAI
client = OpenAI(base_url="https://YOUR_BASE/v1", api_key="sk-xxx")

resp = client.chat.completions.create(
    model="gemini-3.8-flash-app",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "逐镜头描述这段视频，并倒推出提示词"},
        {"type": "video_url", "video_url": "https://your-cdn.com/clip.mp4"},
    ]}],
)
print(resp.choices[0].message.content)
print(resp.usage)   # prompt_tokens 已包含视频 token（时长 x 263）
```

#### 说明
- 图片与视频 已在生产链路实测稳定（同一素材连续 5 次全部正确识别附件内容）。
- 音频 模型对压缩容器（mp3/m4a）的识别不稳定，平台会在转交前统一转成 16kHz 单声道 WAV，并在检测到「模型没收到附件」时自动重试一次；实测转换 + 重试后 8/8 命中。 纯合成音（正弦音等）模型的描述会比较发散 ，语音 / 环境音场景更可靠。
- 附件只在 role: "user" 轮上传；多轮对话里重复贴同一个 URL 不会重复上传，也不会重复计费。

### 响应说明（同步即返，无需轮询）
本接口为 同步对话接口 ，无需轮询。一次 POST 即可在 choices[0].message.content 取得完整回复；设置 stream: true 时按 SSE 标准流式增量推送。

### Python 完整请求
```
from openai import OpenAI
client = OpenAI(base_url="https://YOUR_BASE/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gemini-3.8-flash-app",
    messages=[{"role": "user", "content": "用一句话介绍杭州"}],
)
print(resp.choices[0].message.content)
```

### 联网来源引用（annotations）
当回答触发了联网搜索，我们会把 Gemini 实际引用的网页按 OpenAI 官方 annotations / url_citation 规范 一并返回，同时 正文里的 markdown 链接原样保留 （不会被压成裸域名）。GEO / AEO 监测、引用溯源、竞品可见度分析可直接消费该字段。
| 平台 | 令牌分组 | 支持的模型 |
| 统一网关 newapi.oairegbox.cc | gemini-fast | gemini-3.1-pro · gemini-3.5-flash · gemini-3.1-flash-lite · gemini-3.5-flash-lite · gemini-3.8-flash-app · gemini-2.0-flash-thinking |

#### 非流式：在 choices[].message 下
```
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "…**来源网址**：[semrush.com](https://www.semrush.com/) …",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://www.da-vinci.com.tw/cn/seo-tools",
            "title": "2026年SEO人必看！最新、最齐全的32个SEO软体介绍！"
          }
        }
      ]
    },
    "finish_reason": "stop"
  }]
}
```

#### 流式：在最后一个带 finish_reason 的 chunk 上
stream:true 时正文照常增量下发， 完整的 annotations 随收尾 chunk 一次性给出 （该 chunk finish_reason 非空、 delta.content 为空）。中间 chunk 不会携带引用。
```
data: {"choices":[{"delta":{"content":"…正文…"},"finish_reason":null}]}

data: {"choices":[{"delta":{"annotations":[{"type":"url_citation","url_citation":{"url":"https://…","title":"…"}}]},"finish_reason":"stop"}]}

data: [DONE]
```

#### 字段说明
| 字段 | 说明 |
| type | 固定 "url_citation" |
| url | 必有 。已还原为可直接访问的真实地址，非跳转包装链接；末尾的 #:~:text= 高亮片段已去除，并按 URL 去重 |
| title | 平台给出时返回；取不到则该键省略 |
| start_index / end_index | 不返回 。官方未提供引用与正文字符区间的对应关系，凭空构造会得到错误的定位，故按规范允许的方式省略 |

#### 取引用示例（Python）
```
from openai import OpenAI
client = OpenAI(base_url="https://YOUR_BASE/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "2026年最好用的SEO工具有哪些？请给出来源网址"}],
)
msg = resp.choices[0].message
print(msg.content)
for a in (getattr(msg, "annotations", None) or []):
    c = a["url_citation"] if isinstance(a, dict) else a.url_citation
    print(c.get("title", ""), c["url"])
```

### 注意事项
- 模型名 不带 -fast 后缀 （如 gemini-3.8-flash-app ）。早期带 -fast 后缀的旧名称已下线，继续使用会直接报模型不存在。
- 按 token 计费，分组倍率不同单价不同，以模型广场为准。
- 支持多模态附件：图片、 视频（视频反推） 、音频，见上方「多模态附件」一节；附件按实际体量计入 prompt_tokens 。
- 需要联网引用来源时，见上方「联网来源引用（annotations）」——注意反重力分组不支持。

### 建议
- 直接用 OpenAI SDK（改 base_url + api_key ）接入最省事。
- 大输出 / 长响应建议开 stream 改善体验。

---

# DeepSeek 文本模型
来源：https://docs.oairegbox.cc/#sec-deepseek

## DeepSeek 文本模型
DeepSeek V4.1 Flash 对话模型，OpenAI Chat 兼容，1M 上下文，支持缓存命中优惠。 按北京时间分高峰 / 空闲两档计价 ：周末全天与工作日非高峰时段都按空闲价。

### 模型与价格
| 模型 | 能力 | 计费 |
| deepseek-v4-1-flash-260910 | DeepSeek V4.1 Flash（260910 版），1M 上下文，默认带思考 | 按 token，分时段 |
| 时段（北京时间） | 输入 | 输出 | 缓存命中输入 |
| 空闲 ：周末全天；周一至周五 0:00–9:00、12:00–14:00、18:00–24:00 | ¥0.63 / 百万 token | ¥2.53 / 百万 token | ¥0.0127 / 百万 token |
| 高峰 ：周一至周五 9:00–12:00、14:00–18:00 | ¥1.26 / 百万 token | ¥5.06 / 百万 token | ¥0.0254 / 百万 token |

### 接口信息
| 项 | 说明 |
| 请求 | POST /v1/chat/completions （OpenAI 兼容，同步； stream:true 可流式） |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | DeepSeek （auto 令牌直接可用） |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | deepseek-v4-1-flash-260910 |
| messages | array | 是 | - | OpenAI 消息数组 |
| stream | bool | 否 | false | 是否流式返回 |
| max_tokens | int | 否 | - | 最大输出 token。 思考内容也计入输出并占用此上限 ，开启思考时请给足（建议 ≥ 1024），否则可能只拿到空正文 |
| thinking | object | 否 | 开启 | {"type":"disabled"} 关闭思考，直接出正文、更快更省； {"type":"enabled"} 开启 |
| temperature | number | 否 | - | 采样温度 |

### 示例请求
```
# 关闭思考，直接回答
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash-260910",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    "thinking": {"type": "disabled"}
  }'

# 开启思考（默认），流式输出
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash-260910",
    "messages": [{"role": "user", "content": "用三点总结人工智能的发展趋势"}],
    "max_tokens": 4096,
    "stream": true
  }'
```

### 注意事项
- 默认开启思考：返回的 usage.completion_tokens_details.reasoning_tokens 是思考部分，按输出价计费；不需要思考时加 "thinking": {"type": "disabled"} 。
- 高峰 / 空闲以结算时刻判定，跨时段的长请求按完成那一刻计。
- 缓存命中：同一前缀重复提交时，命中部分按缓存价计， usage 里可看到命中数。

---

# Gemini 图像生成
来源：https://docs.oairegbox.cc/#sec-gemini-image

## Gemini 图像生成
提供两条 Gemini 图像生成线路： gemini-fast 分组 （固定按张计费，走 POST /v1/images/generations 标准生图接口）与 gemini-vertex 分组 （Google Vertex AI 官方原生模型 gemini-3-pro-image 等，按 token 计费，走 POST /v1/chat/completions 或 /v1beta 原生接口）。

### 模型与价格

#### 1. gemini-fast 分组（按次计费 · /v1/images/generations ）
| 模型 | 分组 | 计费 | 价格 | 调用端点 |
| gemini-image | gemini-fast | 按次 | ¥0.11/张 | POST /v1/images/generations / /v1/images/edits |
| gemini-image-pro | gemini-fast | 按次 | ¥0.12/张 | POST /v1/images/generations / /v1/images/edits |

#### 2. gemini-vertex 分组（Google Vertex AI 官方原生模型 · 按 token 计费）
| 模型 | 定位说明 | 分组（倍率 1.8） | 实际单价（入 / 出 / 缓存） | 单张图片预估 | 调用端点 |
| gemini-3-pro-image | Nano Banana Pro 旗舰原生多模态生图 / 图文编辑 | gemini-vertex | 入 ¥3.6/M · 出 ¥216/M · 缓存 ¥0.36/M | 约 ¥0.27 ~ ¥0.29 / 张 | POST /v1/chat/completions POST /v1beta/models/gemini-3-pro-image:generateContent |
| gemini-3.1-flash-image | Nano Banana 2 轻量高速原生生图 | gemini-vertex | 入 ¥0.9/M · 出 ¥108/M · 缓存 ¥0.09/M | 约 ¥0.13 ~ ¥0.15 / 张 | 同上 |
| gemini-2.5-flash-image | Gemini 2.5 Flash 原生生图 | gemini-vertex | 入 ¥0.54/M · 出 ¥54/M · 缓存 ¥0.054/M | 约 ¥0.07 ~ ¥0.08 / 张 | 同上 |

### 接口信息（ gemini-image / gemini-image-pro ）
通过 POST /v1/images/generations 调用，参数与 GPT-Image-2 类似。

### 示例请求
```
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-image",
    "prompt": "赛博朋克风格的东京夜景",
    "size": "1024x1024"
  }'
```

### 核心参数
| 参数 | 类型 | 必填 | 说明 |
| model | string | 是 | gemini-image / gemini-image-pro |
| prompt | string | 是 | 图片描述 |
| size | string | 否 | 控制横 / 竖 / 方画幅，详见下方「画幅与方向」；竖屏为尽力而为 |
| image / images | string / string[] | 否 | 参考图（图生图 / 编辑），单张字符串或多张数组，公网 URL 或 base64；最多 5 张、每张 ≤ 5MB |
| mask | string | 否 | 蒙版图，局部重绘可选 |

### 提交方式
| 模式 | 端点 | 参考图 |
| 文生图 | POST /v1/images/generations （JSON） | 无 |
| 图生图 / 编辑 | 同一端点（JSON），或 /v1/images/edits | image 字段（URL 或 base64，单张或数组） |

### 画幅与方向（size）
size 决定出图方向。现已支持 任意像素尺寸 与方向关键词，网关会据此让模型生成对应画幅：
| size 取值 | 方向 | 说明 |
| 1024x1024 / 512x512 （宽=高） | 方形 1:1 | 默认方向 |
| 1024x1824 / 720x1280 （高>宽） | 竖屏 9:16 | 宽小于高即竖屏 |
| 1824x1024 / 1280x720 （宽>高） | 横屏 16:9 | 宽大于高即横屏 |
| portrait / vertical | 竖屏 9:16 | 方向关键词 |
| landscape / horizontal | 横屏 16:9 | 方向关键词 |
| 9:16 / 16:9 / 1:1 | 按比例 | 直接传纵横比 |

### 参考图（图生图 / 编辑）
附带参考图即可进行图生图 / 编辑。 image 字段 同时支持字符串与数组两种写法 ，取值可为公网 URL 或 data:image Base64：
| 字段 | 类型 | 说明 |
| image | string 或 string[] | 单张参考图（字符串）或多张参考图（数组）均可 |
| images | string[] | 多张参考图数组（与 image 等效） |
| mask | string | 蒙版图，局部重绘可选 |
```
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-image",
    "prompt": "把这两张图融合成一张海报",
    "image": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"]
  }'
```

### 轮询取片
本模型为 同步接口 ，请求成功后直接在响应 data[] 返回图片， 无需轮询 。

### Python 完整请求
```
import requests

BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 文生图（size 传 宽x高 控制方向，竖屏尽力而为）
r = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "gemini-image",
    "prompt": "赛博朋克风格的东京夜景",
    "size": "1024x1824"
}).json()
print(r["data"][0].get("url") or "b64")

# 图生图：image 传单张字符串或多张数组（URL 或 base64）
r2 = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "gemini-image",
    "prompt": "把这两张图融合成一张海报",
    "image": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"]
}).json()
```

### 注意事项
- 竖屏为尽力而为 ：Gemini 对画幅遵循是概率性的，带明确 宽x高 或方向关键词（ portrait / landscape ）可显著提高竖屏命中率。
- 参考图 ： image 传单张字符串或多张数组均可（已兼容早期数组报错），公网 URL 或 base64；最多 5 张、每张 ≤ 5MB。
- 只传单一数字 / 清晰度名 （如 1024 / 2k ）不含方向信息，按模型默认方向出图。

### 建议
- 要竖屏 / 横屏 直接传 宽x高 （如 720x1280 ）或方向关键词，命中率更高。
- pro 更强 ：复杂构图 / 细节用 gemini-image-pro （¥0.12），常规用 gemini-image （¥0.11）。
- 图生图多图 用 image 数组一次传多张融合。

---

# GPT-Image 2.6（1K 标准 & 2K 高清 · Flare / Sunburst 画风 · 原生动态 GIF · 矢量 SVG） Image
来源：https://docs.oairegbox.cc/#sec-gpt-image-2p6

## GPT-Image 2.6（1K 标准 & 2K 高清 · Flare / Sunburst 画风 · 原生动态 GIF · 矢量 SVG） Image

### 一、GPT-Image 2.6 模型与价格表（1K 标准 / Flare & Sunburst 1K·2K / Token 计费）
| 核心模型名 | 所属分组 | 档位定位与画风特性 | 支持分辨率 | 计费方式与价格 | 调用模态支持 |
| gpt-image-2.6 | gpt-fast (已入 auto ) | 1K 标准版（2.6 全功能架构） 支持静态图 + 原生 9 帧动态 GIF + SVG 风格 | 1024x1024 (1:1) 1536x1024 (3:2 横) 1024x1536 (2:3 竖) | 按次：¥0.025 / 张 (生成 GIF 动图同样按单张 ¥0.025 计费) | 同步直出 (10~25s) + async:true 异步轮询 + /v1/chat/completions |
| gpt-image-2.6-flare | gpt-fast (已入 auto ) | 1K Flare（真实摄影质感） 写实人像、商品光影与真实物理细节 | 1024x1024 (1:1) 1536x1024 (横) 1024x1536 (竖) | 按次：¥0.025 / 张 | 同步直出 + async:true 异步轮询 + 视频端点兼容 |
| gpt-image-2.6-sunburst | gpt-fast (已入 auto ) | 1K Sunburst（艺术插画设计） 概念插画、二次元、扁平视觉与海报张力 | 1024x1024 (1:1) 1536x1024 (横) 1024x1536 (竖) | 按次：¥0.025 / 张 | 同步直出 + async:true 异步轮询 + 视频端点兼容 |
| gpt-image-2.6-flare-2k | gpt-fast (已入 auto ) | 2K Flare 高清版（真实摄影） 高分辨率商业级写实摄影与细腻材质 | 2K 高清 ： 2048x2048 (1:1) 2048x1152 / 1152x2048 | 按次：¥0.040 / 张 | 同步直出（超时建议 ≥600s）+ ⭐ async:true 异步轮询 |
| gpt-image-2.6-sunburst-2k | gpt-fast (已入 auto ) | 2K Sunburst 高清版（艺术插画） 高分辨率概念艺术、二次元立绘与海报 | 2K 高清 ： 2048x2048 (1:1) 2048x1152 / 1152x2048 | 按次：¥0.040 / 张 | 同步直出（超时建议 ≥600s）+ ⭐ async:true 异步轮询 |
| gpt-image-2.6-token | Chatgpt | 1K 按 Token 计费版（2.6 架构） 能力与 gpt-image-2.6 完全一致（含 GIF/SVG） | 1024x1024 ( 1056 输出 tok) 1536x1024 / 1024x1536 ( 1584 输出 tok) | 按 Token 计费 ： • 文本输入： ¥1.40 / M • 参考图输入： ¥0.35 / M • 图片输出： ¥14.00 / M (方图约 ¥0.0148/张、横竖图约 ¥0.0222/张，加权均价 ≈ ¥0.025/张 ) | 同步直出 + /v1/images/generations & /v1/images/edits |

### 二、接口端点
| 端点 | 方式 | 默认模态 | 功能说明 |
| POST /v1/images/generations | JSON | 同步直出（传 async:true 转异步） | 标准文生图端点（亦支持在 JSON 中传 image 自动转图生图编辑），适配 OpenAI SDK |
| POST /v1/images/edits | multipart / JSON | 同步直出（传 async:true 转异步） | 图生图 / 图像编辑（参考图 + 提示词描述修改，支持 markup 标注引导） |
| POST /v1/chat/completions | JSON | 同步直出 | Chat 对话生图（在 messages content 中传入文本与 Base64 image_url ） |

### 三、参数字典（含 6 项 GPT-Image 2.6 专属新参数）
| 参数名 | 类型 | 必填 | 默认值 | 详细说明与取值范围 |
| model | string | 是 | - | 可选模型： • 1K 标准/画风版（¥0.025/张）： "gpt-image-2.6" 、 "gpt-image-2.6-flare" 、 "gpt-image-2.6-sunburst" • 2K 高清画风版（¥0.040/张）： "gpt-image-2.6-flare-2k" 、 "gpt-image-2.6-sunburst-2k" • 按 Token 计费版： "gpt-image-2.6-token" （ Chatgpt 组） |
| prompt | string | 是 | - | 画面动作与细节描述词，建议 ≤ 8000 字符 |
| size | string | 否 | "1024x1024" (2K 档默认 "2048x2048" ) | • 1K 模型尺寸 ： "1024x1024" （1:1 方图）、 "1536x1024" （横图）、 "1024x1536" （竖图） • 2K 模型（ -2k ）尺寸 ： "2048x2048" （1:1 方图）、 "2048x1152" （16:9 横图）、 "1152x2048" （9:16 竖图） |
| aspect_ratio / ratio | string | 否 | "1:1" | 画幅比例：支持 "1:1" 、 "16:9" / "3:2" （横图）、 "9:16" / "2:3" （竖图） |
| output_format 2.6 专属 | string | 否 | "png" | 输出文件格式 ： • "png" / "jpeg" / "webp" ：常规静态图片 • "gif" ： 生成原生多帧动态 GIF 动图（ GIF89a ， Content-Type: image/gif ，返回 .gif 直链） • "svg" ：生成干净的矢量插画/图标风格（若底层返回原生 <svg> 则存为 .svg ， Content-Type: image/svg+xml ） |
| frame_count 2.6 专属 | integer | 否 | 9 | 动态 GIF 帧数 （仅当 output_format: "gif" 时生效）：网关强制校验范围 2 ~ 64 （超出范围返回 HTTP 400 不扣费），默认产出 9 帧连贯动画 |
| frame_duration_ms 2.6 专属 | integer | 否 | 自动 | 动态 GIF 单帧停留时长（毫秒） （仅当 output_format: "gif" 时生效）：网关强制校验范围 20 ~ 2000 （即 20ms ~ 2s/帧，超出范围返回 HTTP 400 不扣费） |
| complexity 2.6 专属 | string | 否 | "auto" | 画面构图与细节复杂度 ：可选 "low" （极简扁平/图标）、 "medium" （均衡）、 "high" （高密度细节与复杂光影） |
| background 2.6 专属 | string | 否 | "auto" | 背景透明度控制 ：可选 "transparent" （透明背景，适合贴纸/素材/图标）或 "opaque" （不透明背景） |
| markup 2.6 专属 | string / object | 否 | - | 涂鸦/标注引导图层 （用于 /v1/images/edits 局部引导编辑）：传入带框选/箭头标注的引导图 URL 或 Base64，指导模型按标注位置精准修改 |
| response_format | string | 否 | "url" | 返回格式： "url" （默认下载直链）或 "b64_json" （Base64 编码数据） |
| async | boolean | 否 | false | 默认 false 同步直接返图（10~25s）；设为 true 即刻返回 task_id 供异步轮询 |
| n | integer | 否 | 1 | 单次生成图片张数，默认 1 |

### 四、调用代码示例

#### 1. 生成原生动态 GIF 动图（ output_format: "gif" ）
```
curl -X POST "https://api.oairegbox.cc/v1/images/generations" \
  -H "Authorization: Bearer $OAIREGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6",
    "prompt": "一只戴着宇航员头盔的小柴犬在月球表面开心蹦跳，像素艺术动画风格",
    "size": "1024x1024",
    "output_format": "gif",
    "frame_count": 9,
    "frame_duration_ms": 120
  }'
# 响应示例（单张动图仅扣 ¥0.025，直链后缀为 .gif，Content-Type 为 image/gif）：
# {
#   "created": 1793852817,
#   "data": [
#     {
#       "url": "https://img2.oaibox.xyz/images/2026/11/05/1793852817_f142fdce494bb41dfba3d72ca49be8b5.gif",
#       "revised_prompt": "..."
#     }
#   ]
# }
```

#### 2. 生成 SVG 矢量图标风格 / 透明背景素材（ output_format: "svg" + complexity + background ）
```
curl -X POST "https://api.oairegbox.cc/v1/images/generations" \
  -H "Authorization: Bearer $OAIREGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6",
    "prompt": "极简几何风格的云端 AI 芯片品牌 Logo 图标，线条干净利落",
    "size": "1024x1024",
    "output_format": "svg",
    "complexity": "low",
    "background": "transparent"
  }'
```

#### 3. Chatgpt 分组按量 Token 计费调用（ gpt-image-2.6-token ）
```
# 需使用绑定了 Chatgpt 分组的令牌调用，响应额外包含标准 usage token 明细（单张加权均价 ≈ ¥0.025）
curl -X POST "https://api.oairegbox.cc/v1/images/generations" \
  -H "Authorization: Bearer $CHATGPT_GROUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-token",
    "prompt": "赛博朋克风格的机械狐狸头像，高细节光影",
    "size": "1024x1024",
    "quality": "high",
    "complexity": "high"
  }'
```

#### 4. 图生图编辑（支持 JSON 传 image 或 multipart/form-data ）
```
curl -X POST "https://api.oairegbox.cc/v1/images/edits" \
  -H "Authorization: Bearer $OAIREGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6",
    "prompt": "保留主体构图，将画面转换为 9 帧蒸汽波动态霓虹风格",
    "image": "https://cdn.example.com/portrait.jpg",
    "size": "1024x1536",
    "output_format": "gif",
    "frame_count": 9
  }'
```

---

# GPT-Image-2（1K / 2K / 4K · 全系列支持同步与异步） Image
来源：https://docs.oairegbox.cc/#sec-gpt-image

## GPT-Image-2（1K / 2K / 4K · 全系列支持同步与异步） Image

### 模型与价格
| 核心模型名 | 档位定位 | 标称长边 / 推荐分辨率 | 单价 (元/张) | 同步能力 (Sync) | 异步能力 (Async) |
| gpt-image-2-1k | 1K 基准版 | 1024² (1:1), 1536×1024 (16:9), 1024×1536 (9:16) | ¥0.025 | 10~20s 快速出图返回图片 | 立即返回 task_id，后台轮询取图 |
| gpt-image-2-2k | 2K 高清版 | 2048×2048 (1:1), 2048×1152 (16:9), 1152×2048 (9:16) | ¥0.045 | 支持（需客户端超时 ≥600s，防断连丢图） | ⭐ 强烈推荐 ：立即返回 task_id，轮询取图零丢失 |
| gpt-image-2-4k | 4K 超清版 | 3840×2160 (16:9 真 4K), 2160×3840 (9:16), 2880² (1:1) | ¥0.065 | 支持（需客户端超时 ≥600s，防断连丢图） | ⭐ 强烈推荐 ：立即返回 task_id，轮询取图零丢失 |

### 接口信息
| 端点 | 方式 | 默认模态 | 功能说明 |
| POST /v1/images/generations | JSON | 同步直出（传 async:true 转异步） | 官方原生文生图标准端点，完美适配官方 OpenAI SDK |
| POST /v1/images/edits | multipart / JSON | 同步直出（传 async:true 转异步） | 图生图 / 图像编辑（参考图 + 提示词描述修改） |
| POST /v1/chat/completions | JSON | 同步直出 | Chat 对话生图（在 messages content 中传入 Base64 image_url ） |
| POST /v1/videos 或 /v1/video/generations | JSON | 异步任务轮询 | 存量兼容端点 ：100% 保持历史行为返回 task_id ，老脚本零改动、零报错 |

### 双模态调用机制（同步 / 异步自由切换）

#### 模式 A：默认同步阻塞模式（全面支持官方 OpenAI SDK）
无需额外参数，直接调用即可。网关内部自动等待生成完毕并返回标准 ImageResponse 结构：
```
{
  "created": 1726567200,
  "data": [
    {
      "url": "https://gpt2api.oairegbox.cc/simg/yaimg_xxx.png",
      "b64_json": null
    }
  ]
}
```
开发优势： 完美适配 Python client.images.generate() 、Node.js openai.images.generate() 等官方 SDK，彻底告别以往报 Task object has no attribute 'data' 的痛点！

#### 模式 B：显式异步任务模式（适合大批量并发 / 长耗时任务）
在请求 Body 中传 "async": true ，或在 URL 中添加 ?async=true ，或携带 Header X-New-Api-Async: true 。接口将立即返回任务 ID，规避客户端长连接超时：
```
{
  "id": "task_GEDO8H85WHxQV98z4tM2kEfJMcVxzLlq",
  "status": "queued",
  "created_at": 1726567200
}
```
- 轮询端点： GET /v1/images/generations/{id} （老客户端调 GET /v1/videos/{id} 亦通用）；
- 取片端点： GET /v1/images/generations/{id}/content 或响应内的 image_url / data[0].url 。

### 统一参数字典与多模态输入
| 参数名 | 类型 | 必填 | 默认值 | 详细说明与取值范围 |
| model | string | 是 | - | 模型名： gpt-image-2-1k 、 gpt-image-2-2k 、 gpt-image-2-4k |
| prompt | string | 是 | - | 画面动作与细节描述词。按字符数计（中英文一视同仁），建议 ≤ 8000 字符（硬上限约 1 万字符） |
| size | string | 否 | 依模型 | 精确像素分辨率（如 1024x1024 、 2048x2048 、 3840x2160 等）； size 优先级高于 aspect_ratio |
| aspect_ratio / ratio | string | 否 | 1:1 | 画幅比例，支持 1:1 、 16:9 、 9:16 、 4:3 、 3:4 。平台自动根据模型清晰度档位换算为对应标准像素尺寸 |
| response_format | string | 否 | url | 返回格式： url （默认下载直链）或 b64_json （Base64 编码数据） |
| async | boolean | 否 | false | 是否开启异步任务模式。默认 false 为同步直接返图；设为 true 即刻返回 task_id 供轮询 |
| n | integer | 否 | 1 | 单次生成图片张数，默认 1 |

#### 图生图 / 参考图（Edits）多模态支持说明
平台支持三种灵活的参考图传递方式：
- 方式 1（标准表单上传）： 使用 POST /v1/images/edits ，传 -F "image=@local_file.png" （支持多张重复 -F image=@... ，最多 6 张，解码后合计 ≤ 5MB）；
- 方式 2（JSON 统一传参）： 使用 POST /v1/images/generations 或 /v1/images/edits ，支持在 Body 中传入 image （公网直链或 Base64 data: URI）、 images （数组）、 input_reference 或 metadata.content ，平台全自动兼容提取；
- 方式 3（Chat 对话生图）： 使用 POST /v1/chat/completions ，在 messages 数组的 content 中传入 {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}} 。

### 清晰度档位与真 4K 规格详解
| 模型 | 推荐分辨率 | 约等于 | 像素量 | 典型用途 | 价格 |
| gpt-image-2-1k | 1024×1024 (1:1), 1536×1024 (16:9), 1024×1536 (9:16) | 1K 基准版 | 约 105~157 万 | 头像、缩略图、社媒配图、快速出图 | ¥0.025/张 |
| gpt-image-2-2k | 2048×2048 (1:1), 2048×1152 (16:9), 1152×2048 (9:16) | 2K 高清版 | 约 236~419 万 | 常规海报、Banner、电商主图 | ¥0.045/张 |
| gpt-image-2-4k | 3840×2160 (16:9), 2160×3840 (9:16), 2880×2880 (1:1) | 真 4K UHD | 约 829 万 | 宽屏/竖屏海报、视频封面、影视级超高清大图 | ¥0.065/张 |

### 4K 各画幅尺寸标准
真 4K 长边恒 3840 ，支持任意非方图比例（不再只有 16:9 / 9:16）。传 aspect_ratio 或 size 即按该比例出图、长边保持 3840。 方图 1:1 推荐 2880×2880 或 2K 档 2048² 。下表为实测输出；画幅 不影响计费 ，一律 ¥0.065/张。
| aspect_ratio （或 size ） | 实测输出 | 方向 | 典型用途 |
| 16:9 （不传时默认） | 3840×2160 | 横 | 视频封面 / 宽屏壁纸 / 横版海报 |
| 9:16 | 2160×3840 | 竖 | 手机屏 / 竖版海报 / 短视频封面 |
| 3:4 | 2880×3840 | 竖 | 竖版海报 / 电商详情页 |
| 1:1 方图 | 2880×2880 / 2048×2048 | 方 | 社媒方图 / 高清头像 |

### 调用代码示例

#### 1. 模式 A：默认同步出图（标准 OpenAI 官方 SDK）
```
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR_BASE/v1",
    api_key="sk-你的生图令牌"
)

# 默认同步直出：原生返回 ImageResponse，无需轮询
response = client.images.generate(
    model="gpt-image-2-2k",
    prompt="一只可爱的金毛犬在草地上奔跑，高清写真，柔和晨光",
    size="2048x2048",
    response_format="url"
)

print("图片已生成:", response.data[0].url)
```

#### 2. 模式 A：默认同步出图（curl）
```
curl -X POST https://YOUR_BASE/v1/images/generations   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2-2k",
    "prompt": "一只橘猫趴在窗台上晒太阳，水彩画风格，细节丰富",
    "size": "2048x2048",
    "response_format": "url"
  }'
# 直接返回 {"created": 1726567200, "data": [{"url": "https://...", "b64_json": null}]}
```

#### 3. 模式 B：显式异步任务模式（curl）
```
# ① 提交任务（传 "async": true，立即返回 task_id）
curl -X POST https://YOUR_BASE/v1/images/generations   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2-4k",
    "prompt": "浩瀚星空下的未来科幻都市，霓虹流动，电影级宽银幕",
    "aspect_ratio": "16:9",
    "async": true
  }'
# → {"id": "task_GEDO8H85WHxQV98z4tM2kEfJMcVxzLlq", "status": "queued", ...}

# ② 轮询取图（每 3–5 秒查询一次）
curl -X GET https://YOUR_BASE/v1/images/generations/task_GEDO8H85WHxQV98z4tM2kEfJMcVxzLlq   -H "Authorization: Bearer sk-你的生图令牌"
# 完成后响应中 data[0].url 包含图片直链。

# ③ 成片下载（从 completed 响应里的 url 或直接访问 /content）
curl -L "https://YOUR_BASE/v1/images/generations/task_GEDO8H85WHxQV98z4tM2kEfJMcVxzLlq/content"   -H "Authorization: Bearer sk-你的生图令牌" -o city_4k.png
```

#### 4. 图生图 / 原图编辑（Edits 多模态）
```
# 方式 1：标准 multipart 表单上传（本地文件）
curl -X POST https://YOUR_BASE/v1/images/edits   -H "Authorization: Bearer sk-你的生图令牌"   -F "model=gpt-image-2-2k"   -F "prompt=保留人物主体构图，将背景替换为海边夕阳落日"   -F "image=@portrait.png"

# 方式 2：JSON 传参（支持公网 URL 或 Base64）
curl -X POST https://YOUR_BASE/v1/images/edits   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2-4k",
    "prompt": "保留人物主体不变，将背景改为赛博朋克夜市街道",
    "image": "https://cdn.example.com/portrait.jpg",
    "aspect_ratio": "16:9"
  }'
```

#### 5. Chat 对话生图（POST /v1/chat/completions）
```
curl -X POST https://YOUR_BASE/v1/chat/completions   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2-1k",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "把这张参考图绘制成未来赛博朋克风格的海报"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64>"}}
      ]
    }]
  }'
```

#### 6. 存量兼容端点（POST /v1/videos 保持无感）
```
# 存量老脚本继续请求 /v1/videos，完全保持原有 task_id 异步轮询体验
curl -X POST https://YOUR_BASE/v1/videos   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2-4k",
    "prompt": "a cinematic product poster, ultra sharp",
    "aspect_ratio": "16:9"
  }'
# 返回 task_id，通过 GET /v1/videos/{task_id} 轮询取片，存量业务零修改
```

### Python 完整异步生命周期脚本（4K 实测）
```
import time
import requests

BASE_URL = "https://YOUR_BASE/v1"
TOKEN = "sk-你的生图令牌"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# 1. 提交异步生成任务
resp = requests.post(
    f"{BASE_URL}/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-2-4k",
        "prompt": "雪山脚下清澈见底的高山湖泊，清晨第一缕阳光，超高清摄影",
        "aspect_ratio": "16:9",
        "async": True,
    },
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"异步任务已提交，Task ID: {task_id}")

# 2. 轮询取图（建议间隔 4 秒）
while True:
    time.sleep(4)
    poll = requests.get(f"{BASE_URL}/images/generations/{task_id}", headers=HEADERS).json()
    status = poll.get("status")
    print(f"轮询状态: {status}")
    if status == "completed":
        img_url = poll["data"][0]["url"]
        break
    elif status in ("failed", "failure", "error"):
        raise RuntimeError(f"生成失败: {poll.get('error')}")

# 3. 下载保存成片
img_data = requests.get(img_url, headers=HEADERS).content
with open("lake_4k.png", "wb") as f:
    f.write(img_data)
print("4K 成片已成功保存至本地 lake_4k.png！")
```

### 注意事项（输入格式与错误处理）
- 双模态切换： 默认无需任何参数即为同步出图；需异步排队时仅需传 "async": true 。
- 双端点兼容： 标准端点为 /v1/images/generations 与 /v1/images/edits ；存量 /v1/videos 保持 100% 兼容。
- 提示词长度： 按字符数计（中英文一视同仁），建议控制在 8000 字符以内。
- 参考图大小： 图生图上传参考图单张及合计解码后建议 ≤ 5MiB，支持 Base64 与公网直链。
- 错误处理： 400 参数格式错误不会扣费；任务失败或内容安全拦截均自动免计费。

### 建议
- 1K 快速交互 / SDK 集成 （ gpt-image-2-1k ）可直接使用默认同步模式（10~20s 出图），配合官方 OpenAI SDK 无需写轮询逻辑。
- 2K / 4K 高清与超清生图 （ gpt-image-2-2k 、 gpt-image-2-4k ） 强烈建议必传 "async": true 走异步轮询模式 ，避免因客户端或网关超时（如 300s 限制）断开连接而导致图片丢失；若强走同步模式，请确保客户端与网关超时 ≥ 600 秒。
- 4K 宽屏海报 使用 gpt-image-2-4k 搭配 aspect_ratio: "16:9" 或 "9:16" ，输出标称真 4K（3840×2160 / 2160×3840）。
- 图生图 支持本地文件 multipart 上传与 JSON 传公网直链，灵活适配各类前端与后端。

---

# GPT-Image 2.5（Flare / Sunburst · 全系列支持同步与异步） Image
来源：https://docs.oairegbox.cc/#sec-gpt-image-2p5

## GPT-Image 2.5（Flare / Sunburst · 全系列支持同步与异步） Image

### 模型与价格
| 核心模型名 | 变体定位 | 分辨率规格 | 单价 (元/张) | 调用模态支持 |
| gpt-image-2.5-flare-2k | Flare（真实摄影感） | 2K（2048×2048） | ¥0.040/张 | 同步直出 + 异步轮询 + 视频端点兼容 |
| gpt-image-2.5-flare-4k | Flare（精细摄影） | 真 4K UHD （16:9→3840×2160 / 9:16→2160×3840） | ¥0.065/张 | 同步直出 + 异步轮询 + 视频端点兼容 |
| gpt-image-2.5-sunburst-2k | Sunburst（艺术插画） | 2K（2048×2048） | ¥0.040/张 | 同步直出 + 异步轮询 + 视频端点兼容 |
| gpt-image-2.5-sunburst-4k | Sunburst（超精艺术） | 真 4K UHD （16:9→3840×2160 / 9:16→2160×3840） | ¥0.065/张 | 同步直出 + 异步轮询 + 视频端点兼容 |

### 端点与调用方式
| 调用模式 | 请求端点 | 参数特征 | 出图机制与说明 |
| 异步任务（图片端点 · ⭐强烈推荐） | POST /v1/images/generations 或 /v1/images/edits | 传 "async": true 或 ?async=true | 2K/4K 生产首选（防超时丢图） ：立即返回 {"id": "task_xxx", "status": "queued"} → 轮询 GET /v1/images/generations/{id} → 读 /content |
| 同步出图（默认模态） | POST /v1/images/generations 或 /v1/images/edits | 无需传 async （或 async: false ） | 标准 OpenAI ImageResponse ：直接阻塞返回图片（适配官方 SDK，⚠️ 调用方超时须设 ≥600s，否则断连会导致丢图 ） |
| 异步任务（视频端点兼容） | POST /v1/videos 或 /v1/video/generations | 老视频端点标准格式 | 100% 保持历史行为：返回 task_id → 轮询 GET /v1/videos/{id} → 取 video_url |

### 画幅与尺寸规格
用 aspect_ratio （ 16:9 / 9:16 / 3:4 等）或 size （ WxH ，优先级更高）控制画幅。 2K 档 长边 2048（方图 2048×2048、横版 2048×1152…）； 4K 档 长边恒 3840、真 4K UHD（ 16:9 →3840×2160、 9:16 →2160×3840，其它比例按长边 3840 出）。 4K 无方图 ——方图 1:1 会退回横版 3840×2160，要方图请用 2K（2048²）。 画幅不影响计费。
| aspect_ratio | 2K 档（ -2k ） | 4K 档（ -4k ） |
| 默认（不传）/ 1:1 | 2048×2048 | 3840×2160 （⚠ 4K 无方图 → 退横版） |
| 16:9 | 2048×1152 | 3840×2160 |
| 9:16 | 1152×2048 | 2160×3840 |
| 4:3 | 2048×1536 | 3840×2880 |
| 3:4 | 1536×2048 | 2880×3840 |

### 调用代码示例

#### 1. 模式 A：默认同步出图（标准 OpenAI 官方 Python SDK）
```
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR_BASE/v1",
    api_key="sk-你的生图令牌"
)

# 默认同步直出：无需轮询，直接返回图片
response = client.images.generate(
    model="gpt-image-2.5-flare-2k",
    prompt="a single red apple on a white ceramic plate, studio product photo, soft lighting",
    size="2048x2048",
    response_format="url"
)

print("2.5 Flare 摄影图片生成成功:", response.data[0].url)
```

#### 2. 模式 A：默认同步出图（curl）
```
curl -X POST https://YOUR_BASE/v1/images/generations   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2.5-sunburst-2k",
    "prompt": "futuristic flying car soaring through neon cloudy sky, colorful concept art",
    "size": "2048x2048",
    "response_format": "url"
  }'
# 一次返回标准 ImageResponse，直接获取成片 URL
```

#### 3. 模式 B：显式异步任务模式（curl 4K 示例）
```
# ① 提交任务（传 "async": true，立即返回 task_id）
curl -X POST https://YOUR_BASE/v1/images/generations   -H "Authorization: Bearer sk-你的生图令牌"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2.5-flare-4k",
    "prompt": "a serene mountain lake at sunrise, watercolor, ultra detailed",
    "aspect_ratio": "16:9",
    "async": true
  }'
# → {"id": "task_xxx", "status": "queued", ...}

# ② 轮询取片（每 3–5 秒查询一次）
curl -X GET https://YOUR_BASE/v1/images/generations/task_xxx   -H "Authorization: Bearer sk-你的生图令牌"

# ③ 下载成片
curl -L "https://YOUR_BASE/v1/images/generations/task_xxx/content"   -H "Authorization: Bearer sk-你的生图令牌" -o flare_4k.png
```

#### 4. 图生图 / 原图编辑 · POST /v1/images/edits
用 POST /v1/images/edits 上传原图文件 + 提示词描述改动；亦可在 /v1/images/generations JSON Body 中传入 image 直链或 Base64：
```
curl -X POST https://YOUR_BASE/v1/images/edits   -H "Authorization: Bearer sk-你的生图令牌"   -F "model=gpt-image-2.5-flare-2k"   -F "prompt=repaint the background as a serene blue sky with clouds, keep the subject"   -F "image=@input.png;type=image/png"
```

### 注意事项
- 双模态切换： 默认直接同步返回图片（适配官方 OpenAI SDK）；传入 async: true 时进入异步任务模式，返回 task_id 供轮询。
- 鉴权约定： 请求均需携带 Authorization: Bearer sk-你的生图分组令牌 。
- 计费规则： 按张固定计费、生成失败不扣费、成品纯净无水印。
- 图生图编辑输出尺寸： 编辑模式输出尺寸由模型自适应分配，需精确指定分辨率请使用文生图。

---

# ChatGPT 官方满血生图（纯正官Key直连 · Token实量计费） Official
来源：https://docs.oairegbox.cc/#sec-chatgpt-official-token

## ChatGPT 官方满血生图（纯正官Key直连 · Token实量计费） Official

### 一、官方模型与资费标准
| 模型名称 | 风格定位与特点 | 所属分组 | 官方原价 (汇率7.2) | 本站折后单价 (5.7折) | 单张预估折合成本 |
| gpt-image-2-token | OpenAI 第二代官方旗舰生图底座，支持全分辨率与自由画幅 | Chatgpt (倍率 1.0x) | 输入 $5.00/1M 输出 $30.00/1M (约 ¥36 / ¥216) | 输入 ¥20.50 / 100万 Token 输出 ¥123.00 / 100万 Token | 1K: 约 ¥0.02 ~ ¥0.03/张 2K: 约 ¥0.025/张 4K: 约 ¥0.046 ~ ¥0.081/张 |
| gpt-image-2.5-flare-token | Flare 摄影变体：真实物理世界光影、商品静物、人像纪实 | Chatgpt (倍率 1.0x) | 输入 $5.00/1M 输出 $30.00/1M (约 ¥36 / ¥216) | 输入 ¥20.50 / 100万 Token 输出 ¥123.00 / 100万 Token | 1K: 约 ¥0.02 ~ ¥0.03/张 2K: 约 ¥0.025/张 4K: 约 ¥0.046 ~ ¥0.081/张 |
| gpt-image-2.5-sunburst-token | Sunburst 艺术变体：概念艺术插画、海报设计、视觉张力 | Chatgpt (倍率 1.0x) | 输入 $5.00/1M 输出 $30.00/1M (约 ¥36 / ¥216) | 输入 ¥20.50 / 100万 Token 输出 ¥123.00 / 100万 Token | 1K: 约 ¥0.02 ~ ¥0.03/张 2K: 约 ¥0.025/张 4K: 约 ¥0.046 ~ ¥0.081/张 |

### 二、实测尺寸与画幅矩阵（实测输出分辨率与 Token 消耗）
经平台真机生产验证，本系列模型支持以下 8 档标准尺寸规格。系统原生直出对应画幅，真实输出像素与消耗 Token 实测对照如下：
| 分辨率档位 | 尺寸参数 (size) | 画幅比例 | 实测输出分辨率 | 实测 Token 输出消耗 | 单张实际折算成本 (5.7折) | 典型业务场景 |
| 1K 标清 | 1024x1024 | 1:1 方屏 | 1024 × 1024 | 196 image tokens | 约 ¥0.024 / 张 | 社交头像、商品正方形缩略图、ICON 设计 |
| 1K 标清 | 1536x1024 | 3:2 横屏 | 1536 × 1024 | 158 image tokens | 约 ¥0.019 / 张 | 单反横版摄影、文章博客配图、风景大片 |
| 1K 标清 | 1024x1536 | 2:3 竖屏 | 1024 × 1536 | 158 image tokens | 约 ¥0.019 / 张 | 人像全身写真、手机竖屏壁纸、角色立绘 |
| 2K 高清 | 2560x1440 | 16:9 横屏 | 2560 × 1440 | 205 image tokens | 约 ¥0.025 / 张 | 2K 桌面壁纸、视频 16:9 封面、演示文稿展板 |
| 2K 高清 | 1440x2560 | 9:16 竖屏 | 1440 × 2560 | 205 image tokens | 约 ¥0.025 / 张 | 小红书/抖音高清封面、移动端信息流海报 |
| 真 4K 超清 | 3840x2160 | 16:9 横屏 | 3840 × 2160 | 371 image tokens | 约 ¥0.046 / 张 | 影视级真 4K 巨幕壁纸、高精微距摄影、印刷海报 |
| 真 4K 超清 | 2160x3840 | 9:16 竖屏 | 2160 × 3840 | 371 image tokens | 约 ¥0.046 / 张 | 商用超清竖版灯箱、展会大型展架、精细排版设计 |
| 真 4K 超清 | 2880x2880 | 1:1 方屏 | 2880 × 2880 | 659 image tokens | 约 ¥0.081 / 张 | 超高精细度方形印刷画、高密度艺术设计 |

### 三、调用方式与完整代码示例
采用标准 OpenAI POST /v1/images/generations 同步端点，官方 SDK 与常用网络库零改造兼容：

#### 1. Python 官方 SDK 完整脚本（推荐 · 生产可用）
以下为即插即用的 Python 完整脚本，演示从任务提交、多画幅尺寸指定、解码 Base64 自动保存到本地文件、以及解析 Token 真实用量与折合费用的全流程：
```
import base64
import os
from openai import OpenAI

# 1. 初始化客户端
client = OpenAI(
    base_url="https://api.oairegbox.cc/v1",
    api_key="sk-你的API令牌"  # auto 智能路由令牌或 Chatgpt 分组专属令牌
)

# 2. 支持的标准尺寸常量字典
SIZES = {
    "1k_square": "1024x1024",      # 1K 1:1 方屏
    "1k_landscape": "1536x1024",   # 1K 3:2 单反横版
    "1k_portrait": "1024x1536",    # 1K 2:3 竖版人像
    "2k_landscape": "2560x1440",   # 2K 16:9 宽屏高清
    "2k_portrait": "1440x2560",    # 2K 9:16 手机竖屏
    "4k_landscape": "3840x2160",   # 真 4K 16:9 影视超清
    "4k_portrait": "2160x3840",    # 真 4K 9:16 巨幅海报
    "4k_square": "2880x2880"       # 真 4K 1:1 方屏印刷
}

def generate_official_image(model: str, prompt: str, size: str, output_path: str):
    """
    调用 ChatGPT 官方满血生图接口生成图像并落盘为 PNG 文件
    """
    print(f"🚀 开始生成图片: 模型 [{model}], 尺寸 [{size}]...")
    try:
        response = client.images.generate(
            model=model,
            prompt=prompt,
            size=size
        )

        # 3. 提取官方原生内嵌 C2PA 鉴真的 Base64 图片数据
        b64_data = response.data[0].b64_json
        image_bytes = base64.b64decode(b64_data)

        with open(output_path, "wb") as f:
            f.write(image_bytes)

        file_size_kb = len(image_bytes) / 1024
        print(f"✅ 生成成功！图片已解码保存至: {output_path} ({file_size_kb:.1f} KB)")

        # 4. 解析 Token 实量消耗与扣费情况 (5.7 折: 输入 ¥20.5/M, 输出 ¥123/M)
        if hasattr(response, "usage") and response.usage:
            usage = response.usage
            # 兼容 dict 或对象属性访问
            in_tokens = usage.get("input_tokens", 0) if isinstance(usage, dict) else getattr(usage, "input_tokens", 0)
            out_tokens = usage.get("output_tokens", 0) if isinstance(usage, dict) else getattr(usage, "output_tokens", 0)
            total_tokens = in_tokens + out_tokens
            cost_rmb = (in_tokens * 20.50 + out_tokens * 123.00) / 1000000.0
            print(f"📊 Token 用量: 输入 {in_tokens} tokens, 输出 {out_tokens} tokens (合计 {total_tokens})")
            print(f"💰 真实扣费: ¥{cost_rmb:.5f} 元")

        return output_path

    except Exception as e:
        print(f"❌ 生图失败: {e}")
        return None

if __name__ == "__main__":
    # 示例 A: 真实摄影 Flare 变体生成真 4K 宽屏风景大图
    generate_official_image(
        model="gpt-image-2.5-flare-token",
        prompt="a cinematic macro shot of a dewdrop on a fresh monstera leaf, early morning golden light, 8k professional photography",
        size=SIZES["4k_landscape"],
        output_path="monstera_leaf_4k.png"
    )

    # 示例 B: 概念艺术 Sunburst 变体生成 2K 手机竖屏概念插画
    generate_official_image(
        model="gpt-image-2.5-sunburst-token",
        prompt="a futuristic cyberpunk samurai standing on a neon rain rooftop, vibrant colors, artistic poster",
        size=SIZES["2k_portrait"],
        output_path="cyberpunk_samurai_2k.png"
    )
```

#### 2. Python requests 库原生调用脚本
```
import requests
import base64

API_URL = "https://api.oairegbox.cc/v1/images/generations"
API_KEY = "sk-你的API令牌"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-image-2-token",
    "prompt": "minimalist aesthetic architecture in desert, warm sunlight, clean geometric lines",
    "size": "1536x1024"  # 1K 3:2 单反横版摄影
}

response = requests.post(API_URL, headers=headers, json=payload)
if response.status_code == 200:
    data = response.json()
    b64_json = data["data"][0]["b64_json"]
    with open("desert_architecture.png", "wb") as f:
        f.write(base64.b64decode(b64_json))
    print("✅ 图片生成成功并落盘！")
    usage = data.get("usage", {})
    print(f"Token 用量: 输入 {usage.get('input_tokens')}, 输出 {usage.get('output_tokens')}")
else:
    print(f"❌ 失败 [{response.status_code}]: {response.text}")
```

#### 3. cURL 命令行请求示例
```
# 1. 概念艺术 Sunburst 变体 · 1024x1024 方屏
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst-token",
    "prompt": "futuristic flying car soaring through neon cloudy sky, colorful concept art",
    "size": "1024x1024"
  }'

# 2. 真实摄影 Flare 变体 · 3840x2160 真 4K 超高清
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-token",
    "prompt": "breathtaking sunset over snow mountain peaks, golden sunlight, 8k wallpaper",
    "size": "3840x2160"
  }'
```

### 四、核心优势与版本选型指南
- 官方真 4K 原生渲染 ：支持 size: "3840x2160" 、 "2160x3840" 与 "2880x2880" 原生真 4K 输出，画面微观细节与文字边缘锐利清晰，绝非低清后期超分插值拉伸；
- 纯净交付与正版鉴真 ：全系生成图片默认无水印，保留完整色彩动态范围，且内嵌不可篡改的 C2PA 官方正版数字鉴真签名；
- 业务版本选型建议 ： 走量与日常高性价比场景 ：选用 gpt-fast 分组下的按次生图模型（如 gpt-image-2.6 / gpt-image-2-1k ¥0.025/张一口价）； 高端商用、精细画面与版权鉴真场景 ：选用本系列 Chatgpt 分组下的 -token 官方满血版，享受官方原版画质与 5.7 折实量扣费。

---

# Gemini 音乐生成
来源：https://docs.oairegbox.cc/#sec-gemini-music

## Gemini 音乐生成
通过 Chat Completions 接口生成音乐。 同步返回 （约 40–70 秒），结果是一个 可直接下载的 MP3 链接 （无需鉴权即可 GET 下载）。

### 模型与价格
| 模型 | 价格 | 令牌分组 |
| gemini-music | ¥1.00/首 | gemini-fast |

### 时长档位
提供两个档位，用 length 参数选择：
| 档位 | 目标长度 | 纯音乐实测 | 带人声实测 |
| short （不填时的默认） | 60 秒 | 54–67 秒 中位 62 秒 | 58–155 秒 中位 63 秒，P90 约 103 秒 |
| standard | 180 秒 | 145–180 秒 |

### 关于歌词
默认不会返回歌词文本 ，只会返回一句生成说明。实测 38 个默认用例中，只有 1 个自带了歌词。
想要歌词就在提示词里明确要求 ，例如「 请在回复里把完整歌词逐行写出来 」或指定结构：
```
In your text reply, output the lyrics in this structure:
[Verse 1] ... [Chorus] ... [Verse 2] ...
Write the actual lyric lines, not a description.
```
加了这类要求后，6 个用例中有 5 个返回了带 [Verse] / [Chorus] 结构的完整歌词。歌词出现在 chat 返回正文的分隔线之后，或结构化接口的 message 字段里。

### 请求示例（Chat Completions）
```
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-music",
    "messages": [{"role":"user","content":"创作一首轻快的电子风格BGM，适合科技产品广告"}]
  }'
```
Chat 接口没有结构化参数，系统会 从你的文字里读取意图 ：
- 写「 3分钟 」「 90秒 」「 3 minutes 」→ 归入最接近的档位（不写则按 short ）
- 写「 纯音乐 」「 不要人声 」「 instrumental 」→ 不带人声
- 写「 要有人声 」「 有歌词 」「 with vocals 」→ 带人声演唱
- 都不写 → 交给模型自己决定

### 请求示例（结构化接口）
需要显式控制时用 POST /v1/audio/generations ：
```
curl https://YOUR_BASE/v1/audio/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-music",
    "prompt": "大气的电影配乐，弦乐为主",
    "length": "standard",
    "vocals": false
  }'
```
| 参数 | 类型 | 说明 |
| prompt | string | 必填。曲风、情绪、乐器、用途等描述 |
| length | string | short / standard ，见上方时长档位。不填按 short |
| vocals | bool | true =带人声演唱， false =纯音乐。 不填 =交给模型决定 |
| attachments | string[] | 可选。参考音频或图片，支持 data URI / http(s) URL / 裸 base64，单个 ≤20MB，仅 audio/* 与 image/* |
| duration | int | 旧版数值参数（秒，5–180），仍然可用；同时传 length 时以 length 为准 |
返回体里会回显 length 、 target_seconds 和 duration_is_exact: false ，后者就是在提醒你：那是目标值，不是成品长度。

### 返回示例
下载链接在 choices[0].message.content 里（Markdown 链接 + 纯 URL 各一份）：
```
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "✅ 音乐生成完成\n\n[⬇️ 点击下载音乐](https://download.oaibox.xyz/v1/audio/aud-xxxx.mp3)\n\nhttps://download.oaibox.xyz/v1/audio/aud-xxxx.mp3"
    },
    "finish_reason": "stop"
  }]
}
```
从 content 中取出形如 .../v1/audio/aud-xxxx.mp3 的 URL，直接 GET 即可下载（ 无需带 Authorization ）。响应头为 Content-Type: audio/mpeg + Content-Disposition: attachment ，浏览器、curl、ffmpeg、下载工具都能直接当文件处理。也支持 "stream": true ，链接会在流式结束的那条消息里返回。

### 关于成品格式
交付的一定是 MP3 （立体声 44.1kHz）。生成过程中同时会产出一段带封面动画的 MP4，我们不把它作为音乐成品返回；若本次未直接提供 MP3，系统会从该 MP4 中提取音轨转成 MP3 后再交付，对你是透明的。

---

# Gemini 语音合成（TTS）
来源：https://docs.oairegbox.cc/#sec-gemini-tts

## Gemini 语音合成（TTS）
OpenAI 兼容的文字转语音接口 POST /v1/audio/speech 。 同步返回音频字节流 （ mp3 / opus / pcm 边合成边下发，首包约 0.3–0.5 秒），直接把响应体当音频文件保存即可，无需二次下载。

### 模型与价格
| 模型 | 价格 | 令牌分组 |
| gemini-tts | ¥15 / 100 万字符 （与 OpenAI tts-1 平价） | gemini-fast |

### 请求示例
```
curl https://YOUR_BASE/v1/audio/speech \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-tts",
    "input": "你好，欢迎使用语音合成服务。",
    "voice": "Capella",
    "response_format": "mp3"
  }' --output speech.mp3
```

### 参数
| 参数 | 类型 | 说明 |
| model | string | 必填，固定 gemini-tts |
| input | string | 必填。要朗读的文本，中英文混排均可。服务端 按文本自动识别语言 |
| voice | string | 音色，见下表。不填用默认音色。 OpenAI 音色名（alloy/nova/echo…）也接受 ，会按性别映射到对应 Gemini 音色 |
| response_format | string | mp3 （默认）/ opus / aac / flac / wav / pcm |
| speed | float | 语速 0.25 – 4.0 ，默认 1.0 。官方源站不支持变速，由本平台用音频后处理实现，不影响音色 |
| language | string | 可选 BCP-47 口音提示（如 es-ES vs es-US ）。只选地区变体，不决定语种——语种由文本自动判定 |

### 音色列表
9 个音色，跨语言通用（中文、英文等都用同一组名字）：
| 性别 | 音色名 |
| 女声 | Capella · Ursa · Vega · Eclipse · Lyra |
| 男声 | Orbit · Dipper · Nova · Pegasus |

### 说明
- 响应体就是音频本身： mp3 / opus / pcm 为流式下发， wav / aac / flac 合成完再整体返回。
- 速度参考：约 30–40ms/字符。4000 字英文约 36 秒、1800 字中文约 65 秒合成完毕。
- 语速、音高这类字段官方源站一律忽略； speed 由平台用变速后处理保证可用。

---

# Gemini 语音识别（STT）
来源：https://docs.oairegbox.cc/#sec-gemini-stt

## Gemini 语音识别（STT）
OpenAI 兼容的语音转文字接口 POST /v1/audio/transcriptions （ multipart/form-data 上传音频文件）。同步返回转写文本，任意常见音频容器都接受，平台会自动转码。

### 模型与价格
| 模型 | 价格 | 令牌分组 |
| gemini-stt | $0.006 / 分钟 （与 OpenAI whisper 平价） | gemini-fast |

### 请求示例
```
curl https://YOUR_BASE/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxx" \
  -F model=gemini-stt \
  -F file=@audio.mp3 \
  -F language=zh \
  -F response_format=json
```

### 参数
| 参数 | 类型 | 说明 |
| file | file | 必填。音频文件，≤25MB。mp3/wav/m4a/ogg/webm 等常见格式均可，平台自动转码 |
| model | string | 固定 gemini-stt ，不填默认即此 |
| language | string | 可选。语言提示，如 zh / en （会归一化为 cmn-Hans-CN / en-US ）。不填默认英文为主、中文为辅自动识别 |
| response_format | string | json （默认， {"text":...} ）/ verbose_json / text 。 不支持 srt / vtt （无逐词时间戳） |

### 返回示例
```
{ "text": "你好，这是一段语音识别测试。" }
```
verbose_json 额外返回 task 、 language 、 duration （音频秒数）字段； text 则直接返回纯文本。无语音内容时返回空串，不算失败。

---

# Gemini 语音对话（Voice Chat）
来源：https://docs.oairegbox.cc/#sec-gemini-voice

## Gemini 语音对话（Voice Chat）
把 语音识别（STT）→ 对话（Chat）→ 语音合成（TTS） 合成一次调用： 说一句话进去，得到一段语音回答 。一问一答（turn-based）、支持中英文、跑在同一个号池上。

### 价格
按 所用对话模型的文本计费 （即你在 model 里填的那个 Gemini 对话模型的价格）。语音识别与语音合成这两段 不额外收费 。失败不计费。

### 用法一：OpenAI 兼容（/v1/chat/completions）
在普通对话请求里加 modalities:["text","audio"] 和 audio 两个字段即可，和 OpenAI 的 gpt-4o-audio 完全一致。 用你现有的对话模型 ，无需申请新模型。
```
curl https://YOUR_BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "modalities": ["text", "audio"],
    "audio": { "voice": "nova", "format": "mp3", "input_mode": "stt" },
    "messages": [
      { "role": "user", "content": [
        { "type": "input_audio", "input_audio": { "data": "<base64音频>", "format": "mp3" } }
      ]}
    ]
  }'
```
返回里，文字回答在 choices[0].message.content ，语音回答在 choices[0].message.audio ：
```
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "2 加 3 等于 5。",
      "audio": {
        "id": "audio_xxxx",
        "data": "<base64 的 mp3>",
        "transcript": "2 加 3 等于 5。",
        "format": "mp3"
      }
    }
  }]
}
```
| 字段 | 说明 |
| modalities | 必须包含 "audio" 才会返回语音 |
| audio.voice | 音色，见下方列表（OpenAI 音色名如 nova / alloy 也接受） |
| audio.format | mp3 （默认）/ opus / aac / flac / wav / pcm |
| audio.input_mode | stt （默认，先转文字，便宜、附带识别文本）/ native （让模型直接"听"音频，懂语气但更贵） |
| input_audio | 语音输入（可选）。也可以用纯文字提问、只要语音回答。输入的识别文本会放在响应头 X-Input-Transcript （base64） |

### 用法二：直连语音端点（/v1/audio/chat）
给原生音频应用准备的精简端点： multipart 上传音频，直接吐回 音频字节流 。此端点 需直连网关 使用。
```
curl https://YOUR_BASE/v1/audio/chat \
  -H "Authorization: Bearer sk-xxx" \
  -F model=gemini-voice \
  -F file=@question.mp3 \
  -F voice=Capella \
  -F response_format=mp3 \
  -F input_mode=stt \
  -F language=zh \
  --output answer.mp3
```
默认返回音频文件，识别文本与回答文本在响应头 X-Transcript / X-Reply-Text （都做了 base64 编码，避免中文乱码）。传 response_format=json 则返回 { "transcript": "...", "text": "...", "audio": { "data": "<base64>", "format": "mp3" } } 。可选 messages 字段（JSON 数组）带对话上下文， speed 调语速（0.25–4.0）。

### 音色列表
| 性别 | 音色名 |
| 女声 | Capella · Ursa · Vega · Eclipse · Lyra |
| 男声 | Orbit · Dipper · Nova · Pegasus |

---

# 通用说明 & FAQ
来源：https://docs.oairegbox.cc/#sec-common

## 通用说明 & FAQ

### 接入地址（两条独立线路，同一账号）
| 线路 | Base URL | 入口位置 | 适用场景 |
| 主线路 | https://api.oairegbox.cc/v1 | 欧洲 | 默认使用；本文档所有示例均用此地址 |
| 备用线路 | https://newapi.oairegbox.cc/v1 | 美东 | 主线路连不上 / 延迟偏高时改用， 只改域名，其他一行不动 |

### 鉴权
所有请求需携带 Authorization: Bearer sk-你的令牌 请求头。令牌在后台「令牌」页创建， 分组必须与模型匹配 （错误分组会返回"无可用渠道"）。

### 错误码
| HTTP | 含义 | 处理 | 计费 |
| 200 | 成功 | 正常取用 | 成功才扣 |
| 400 | 参数/素材问题 | 按 message 改正 | 不计费 |
| 401 | 鉴权失败 | 检查令牌 | 不计费 |
| 403 | 余额或令牌额度低于预扣门槛 | 见下方「预扣费机制与测试充值参考」：充值、将令牌设为无限额度、或调小视频秒数 | 不计费 |
| 404 | 路径错误 | 检查 URL（勿重复 /v1） | 不计费 |
| 429 | 限速/额度不足 | 降并发或充值 | 不计费 |
| 502/5xx | 服务端临时故障 | 直接重试 | 不计费 |

### 💰 全站预扣费机制与首次测试充值参考
| 模型类别 / 代表模型 | 计费模式 | 单次提交预扣额度 | 完成后实际扣费 | 首次测试建议充值 |
| Omni / Flow / Muse 视频 & 全系生图 omni-fast (¥0.37)、 omni-fast-no-water (¥0.47)、 flow-omni-1.1-flash (¥0.75/¥0.90)、 muse-video (¥0.30~¥1.20)、 gpt-image-2.6 (¥0.025)、 gpt-image-2-1k/2k/4k (¥0.025~¥0.065)、 doubao-seedream (¥0.225~¥0.495)、 qwen-image-3.0-pro (¥0.25~¥0.50) | 按次 | = 单次售价（¥0.025 ～ ¥1.20） | = 预扣金额（失败全退） | ¥5 即可畅测多笔 |
| Grok / Flow Omni 1.2 / MiniMax / 通义万相 3.0 grok-imagine-video-1.5 (¥0.058~¥0.15/秒)、 flow-omni-1.2-flash (¥0.11/秒)、 minimax-h3-768p/2k (¥0.15~¥0.33/秒)、 wan3.0-video (¥0.21~¥0.84/秒) | 按秒 | 每秒单价 × 秒数（5秒预扣 ¥0.29 ～ ¥4.20） | 按实际出片秒数结算 | ¥5 即可测（ wan3.0-video-prime 1080p 5秒需 ¥7.60，建议充 ¥10） |
| 快手可灵 Kling-v3 & 自定义 sd-* kling-v3-standard (¥0.765/秒)、 kling-v3-pro (¥1.02/秒)、 kling-v3-4k (¥2.55/秒)； sd-2.5 (默认15秒) | 按秒 / 按次 | Kling 5秒：标清 ¥3.83 / Pro ¥5.10 / 4K ¥12.75； sd-2.5 不传时长默认按15秒预扣（720p ¥12.00，传5秒则 ¥4.00） | = 预扣金额（失败全退） | 测 Kling 标清充 ¥5；测 Kling Pro 充 ¥10；测 4K 充 ¥15+ |
| Seedance 2.0 Mini 经济档 seedance-2.0-mini-720p 、 doubao-seedance-2.0-mini-480p/720p | 按 Token | 无视频 ¥0.40~¥0.60/秒（5秒预扣 ¥2.00 ～ ¥3.00 ；1080p 5秒预扣 ¥7.40） | 5秒实扣约 ¥0.90 ～ ¥1.44（差额自动退回） | ¥5 即可测 480p/720p；测 1080p 充 ¥10 |
| Seedance 2.0 Fast / 标准 / Pro 720p seedance-2.0-fast-720p 、 doubao-seedance-2.0-fast-720p 、 seedance-2.0-720p 、 doubao-seedance-2.0-pro-720p | 按 Token | 无视频 ¥1.08~¥1.61/秒： • seedance-2.0-fast-720p ：4秒预扣 ¥4.33 、 5秒预扣 ¥5.41 、10秒预扣 ¥10.82 • pro-720p ：5秒预扣 ¥8.07 | 5秒实扣约 ¥2.60 ～ ¥3.87（完成后退回约一半） | 建议充 ¥10 ～ ¥15（充 ¥5 仅够测 4 秒 fast-720p ） |
| Seedance 2.0 1080p/4K & Seedance 2.5 全系 seedance-2.5-720p 、 doubao-seedance-2.5-720p/1080p 、 doubao-seedance-2.0-fast/pro-1080p 、 pro-4k | 按 Token | 无视频 ¥2.45~¥6.16/秒： • 2.5-720p ：4秒预扣 ¥9.80~¥11.20、5秒预扣 ¥12.25~¥14.00 • pro-1080p / pro-4k ：5秒预扣 ¥19.89 / ¥22.31 • 2.5-1080p ：5秒预扣 ¥30.80 | 5秒实扣约 ¥5.30 ～ ¥19.71（差额自动退回；带参考视频预扣与实扣均低约 40%） | 测 2.5-720p / 2.0-1080p 建议充 ¥15～¥30；测 2.5-1080p / 4K 建议充 ¥35～¥65 |

### FAQ

#### Q: Oairegbox 是用来注册 OpenAI 账号，或接收验证码的吗？
不是。Oairegbox 只提供 API 调用接入，不提供账号注册、手机接码或验证码代收。

#### Q: 为什么刚充了 5 元（或账户还有余额），调用视频模型却提示「资源不足」？
这是触发了 提交预扣冻结校验 而非扣费异常：例如 seedance-2.0-fast-720p 不带参考视频生成 5 秒虽然最终实扣仅约 ¥2.60 ，但提交瞬间需按上限预扣冻结 ¥5.41 （生成完成后自动退回差额约 ¥2.81）；同理 kling-v3-pro 5 秒需预扣 ¥5.10 。解决方法：① 小额测试时将视频时长 duration / seconds 改为最短 4 秒 （ seedance-2.0-fast-720p 4 秒仅预扣 ¥4.33）；② 按上方「预扣费机制与首次测试充值参考」表补充余额（测 Seedance 720p 建议充 ¥10～¥15）；③ 检查后台「令牌」是否限制了可用额度（建议设为无限额度）。

#### Q: 视频生成需要多久？
Omni 视频约 1-5 分钟，Grok 视频约 30s-3 分钟（时长越长越慢）。建议客户端超时 ≥300 秒。

#### Q: 失败会扣费吗？
不会。所有模型失败一律不扣费，仅成功出片/出图才计费。

#### Q: 参考图被内容策略拒绝怎么办？
包含可识别真人面孔的参考图可能触发 Gemini 内容策略。系统会自动尝试处理并重试。如仍失败，建议：使用非写实风格、虚构人物、侧面/背影/远景，或使用已授权的素材。

#### Q: 有多个接入地址，该用哪个？它们是不同账号吗？
不是不同账号 ——所有地址指向 同一个平台 ，账号、令牌、余额、模型与价格 完全通用 ，随时可以互换， 不需要重新注册、也不需要重新充值 。默认用主线路 api.oairegbox.cc ；若你所在网络连不上或延迟偏高，改用备用线路 newapi.oairegbox.cc （美东入口）再试一次。两条线路对不同地区 / 运营商各有优劣，我方不承诺哪条更快。

---

# 视频生成 · 内容审查避坑指南
来源：https://docs.oairegbox.cc/#sec-video-guide

## 视频生成 · 内容审查避坑指南
适用于 omni-fast / veo 系列视频模型 · 帮你避开 Google 内容审查，提高一次出片成功率

### 一、先看这条报错
如果你收到：
中文意思： 请求没通过内容审查 （可能涉及：可识别真人 / 不安全内容 / 受保护版权）。

### 二、六大高危雷区（命中必拒）
- 写实真人正脸、特写人像
- 任何 名人、明星、政治人物、网红 的名字或长相
- 上传 真人照片 当参考图（尤其正脸特写）
- 🔑 photorealistic （超写实）+ 真人 = 高危组合
- 画面出现 儿童 / 婴儿 / 青少年 / 学生
- 哪怕本意无害，未成年人 + 任何危险或暧昧情境都会被拒
- 裸露、性感、情色、内衣、暧昧亲密、床戏、诱惑等
- 暴力、血腥、武器、打斗、战争、爆炸
- 自杀、自残、事故、伤口、尸体、虐待
- 危险动作 / 危险情境
- 动漫游戏角色 ：皮卡丘、马里奥、奥特曼、米老鼠、艾莎、蜘蛛侠、哆啦A梦、火影等
- 品牌商标 ：Nike、苹果、迪士尼、可口可乐、LV 等任何 logo
- 影视形象 ：具名电影/电视剧角色、海报、截图
- 医疗病症 ：皮肤病、痤疮、湿疹、体味、伤口、疾病 ← 真实案例踩过
- 政治 / 宗教 ：领导人、宗教冲突、种族议题
- 毒品 / 违法 ：毒品、吸毒等
- 仇恨 / 歧视 言论

### 三、安全改写对照表
| ❌ 高危写法 | ✅ 安全改写 |
| 超写实真人 + 正脸特写 | 改 3D动画 / 插画 / 卡通 风格；或侧面、背面、远景 |
| 上传真人照片生成 | 不要正脸；用远景/侧背面；或转动漫/卡通风格 |
| 奥特曼大战怪兽 | 「一个通用的巨人英雄」（不点名具体 IP） |
| 情侣处理痤疮/皮肤病 | 去掉病名，改成中性的「情侣约会」 |
| 小孩在火边玩耍 | 改成「成年人」，或移除危险元素 |
| 含名人姓名 | 改成「一位虚构的人物」 |

### 四、万能保险公式
不确定会不会被拒时，套这个组合最稳：
```
非写实风格 (non-photorealistic / 3D cartoon / illustration / anime)
+ 虚构、不具名的主体 (fictional, non-identifiable subject)
+ 脸部不可识别 (背面 / 侧面 / 远景)
+ 内容健康、无版权
```

### 五、提交前自检清单
- ☐ 有没有 真人/名人 ？→ 转非写实风格或脸部不可识别
- ☐ 有没有 儿童/青少年 ？→ 移除或改成年人
- ☐ 有没有 性/暴力/危险/血腥 ？→ 删除相关描述
- ☐ 有没有 动漫角色/品牌/影视 IP ？→ 换原创通用描述
- ☐ 有没有 病症/政治/毒品 等敏感词？→ 中性化
- ☐ 参考图是不是 真人照片 ？→ 换非写实图或远景

---

# MiniMax H3 · 按秒计费（768P / 2K）
来源：https://docs.oairegbox.cc/#sec-minimax-h3-persec

## MiniMax H3 · 按秒计费（768P / 2K）
MiniMax H3 按秒计费 ，两档清晰度、 原生音频 。支持文生 / 图生 / 首尾帧 / 参考图 / 参考音频；需 参考视频 驱动用 Pro 档 。同一套 /v1/videos 接口：异步创建 → 轮询 → 下载。

### 模型与价格
| 模型 | 清晰度 | 全能参考 | 计费 | 价格 | 时长 |
| minimax-h3-768p | 768P | 503 | 按秒 | ¥0.15/秒 | 4–15 秒 |
| minimax-h3-2k | 2K | 503 | 按秒 | ¥0.20/秒 | 4–15 秒 |
| minimax-h3-pro-768p | 768P | 913 | 按秒 | ¥0.25/秒 | 4–15 秒 |
| minimax-h3-pro-2k | 2K | 913 | 按秒 | ¥0.33/秒 | 4–15 秒 |

### 接口信息
| 项 | 说明 |
| 提交任务 | POST /v1/videos （JSON） |
| 轮询进度 | GET /v1/videos/{task_id} |
| 下载成片 | 完成后响应里的 video_url 直链 |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | minimax |

### 核心参数
| 字段 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 上表四个之一 |
| prompt | string | 是 | - | 提示词， ≤7000 字符（超出会被静默截断） |
| duration | integer | 否 | - | 4–15 秒（= 计费秒数） |
| ratio | string | 否 | - | 16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4 / adaptive （文生视频不支持 adaptive） |
| referenceImages | string[] | 否 | - | 参考图 ≤5 （公网 URL 或 base64） |
| referenceAudios | string[] | 否 | - | 参考音频 ≤3 （须配参考图；合计 ≤15 秒） |
| referenceVideos | string[] | 否 | - | Pro 档专用 ：1 段，时长 2–5 秒 |
| first_image / last_image | string | 否 | - | 首/尾帧； 不能与 referenceImages 同用 |

### 提交方式
JSON，参考素材支持 公网 URL 或 base64 。按传入素材自动判定模式：
| 模式 | 最少必传 |
| 文生视频 | prompt |
| 图生视频 | prompt + referenceImages （≤5） |
| 首尾帧 | first_image （+ last_image ）；不与普通参考图同用 |
| 参考视频驱动 | Pro 档 + referenceVideos （1 段 2–5 秒） |

### 示例请求
```
# 文生视频
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-2k","prompt":"A calm ocean wave at golden sunset, cinematic","duration":5,"ratio":"16:9"}'

# 图生视频（参考图 · URL）
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-768p","prompt":"角色转身微笑，镜头缓慢推近","duration":6,
       "referenceImages":["https://你的公网图片地址/ref1.jpg"]}'

# 图生视频（参考图 · base64，任何图片都可用、最稳妥）
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-768p","prompt":"角色转身微笑，镜头缓慢推近","duration":6,
       "referenceImages":["data:image/jpeg;base64,/9j/4AAQ...（整段图片 base64）"]}'

# 参考视频驱动（Pro，1 段 2-5 秒）
curl https://newapi-2.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3-pro-768p","prompt":"角色跟随参考视频的动作与镜头运动","duration":5,
       "referenceVideos":["https://.../ref.mp4"]}'
```

### 轮询取片
```
curl https://newapi-2.oairegbox.cc/v1/videos/TASK_ID -H "Authorization: Bearer $TOKEN"
# status=completed 后用响应里的 video_url 下载
curl -L "VIDEO_URL" -o result.mp4
```

### Python 完整请求
```
import time, requests
BASE = "https://newapi-2.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-你的minimax令牌", "Content-Type": "application/json"}
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "minimax-h3-2k",
    "prompt": "A calm ocean wave at golden sunset, cinematic",
    "duration": 5, "ratio": "16:9",
}).json()
tid = task["task_id"]
while True:
    r = requests.get(f"{BASE}/videos/{tid}", headers=H).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(5)
url = r.get("video_url") or (r.get("data") or [{}])[0].get("url")
open("minimax.mp4", "wb").write(requests.get(url).content)
```

### 注意事项
- 严格内容审核 ：违规提示词直接 400（不产任务、不计费），屡犯可能致模型临时不可用。
- prompt ≤7000 字符，超出静默截断 ——长提示词请自行精简，别指望超出部分生效。
- 用 ratio 字段控画幅（不是 size/aspect_ratio）；文生视频不支持 adaptive 。
- first_image / last_image 与 referenceImages 互斥；参考音频须配参考图。
- 参考素材 URL 必须公网可直接访问 ；访问受限的地址会报 cannot download media URL ——改用 base64 （ data:...;base64, ）即可，任何图 / 视频都行。
- 参考视频仅 Pro 档、1 段 2–5 秒；2K / 参考视频出片较慢，高峰期偶发排队请重试。

### 建议
- 走量用 768P，画质优先用 2K；需要视频驱动动作 / 运镜才用 Pro 档。
- 竖屏传 ratio":"9:16" ；参考视频请截取你要的关键 2–5 秒片段。
- 提示词全英文或中文均可，但务必合规、避免任何擦边表述。

---

# Seedance 2.0 / 2.5 · 官方直连 Video
来源：https://docs.oairegbox.cc/#sec-seedance20-direct

## Seedance 2.0 / 2.5 · 官方直连 Video

### 模型与价格
| 模型 | 档位 · 分辨率 | 计费 | ¥/百万token （纯文/图生） | ¥/百万token （含参考视频） | 折合每秒（含视频特惠） | 折合每秒（纯文/图生） | 典型 5 秒预计 | 官方折扣 |
| seedance-2.0-720p | 720p（特惠线） | 按token | ¥28.98 | ¥17.64 | 约 ¥0.38/秒 | 约 ¥0.63/秒 | 约 ¥1.90 ~ ¥3.13 | 6.3 折 |
| seedance-2.0-fast-720p | fast · 720p（特惠线） | 按token | ¥24.05 | ¥14.30 | 约 ¥0.31/秒 | 约 ¥0.52/秒 | 约 ¥1.55 ~ ¥2.60 | 6.5 折 |
| seedance-2.0-mini-720p | mini · 720p（特惠线） | 按token | ¥10.35 | ¥6.30 | 约 ¥0.14/秒 | 约 ¥0.22/秒 | 约 ¥0.68 ~ ¥1.12 | 4.5 折 |
| seedance-2.5-720p | 2.5 · 720p（特惠线） | 按token | ¥49.00 | ¥29.40 | 约 ¥0.64/秒 | 约 ¥1.06/秒 | 约 ¥3.18 ~ ¥5.30 | 7 折 |
| doubao-seedance-2.0-mini-480p | mini · 480p | 按token | ¥13.34 | ¥7.70 | 约 ¥0.10/秒 | 约 ¥0.18/秒 | 约 ¥0.52 ~ ¥0.90 | 5.8 折 |
| doubao-seedance-2.0-mini-720p | mini · 720p | 按token | ¥13.34 | ¥7.70 | 约 ¥0.17/秒 | 约 ¥0.29/秒 | 约 ¥0.83 ~ ¥1.44 | 5.8 折 |
| doubao-seedance-2.0-mini-1080p | mini · 1080p | 按token | ¥14.79 | ¥8.525 | 约 ¥0.41/秒 | 约 ¥0.72/秒 | 约 ¥2.07 ~ ¥3.59 | 5.8 折 |
| doubao-seedance-2.0-fast-480p | fast · 480p | 按token | ¥25.90 | ¥15.40 | 约 ¥0.21/秒 | 约 ¥0.35/秒 | 约 ¥1.04 ~ ¥1.76 | 7 折 |
| doubao-seedance-2.0-fast-720p | fast · 720p | 按token | ¥25.90 | ¥15.40 | 约 ¥0.33/秒 | 约 ¥0.56/秒 | 约 ¥1.66 ~ ¥2.80 | 7 折 |
| doubao-seedance-2.0-fast-1080p | fast · 1080p | 按token | ¥28.35 | ¥17.15 | 约 ¥0.83/秒 | 约 ¥1.38/秒 | 约 ¥4.17 ~ ¥6.89 | 7 折 |
| doubao-seedance-2.0-pro-480p | pro（满血）· 480p | 按token | ¥35.88 | ¥21.00 | 约 ¥0.28/秒 | 约 ¥0.49/秒 | 约 ¥1.42 ~ ¥2.43 | 7.8 折 |
| doubao-seedance-2.0-pro-720p | pro（满血）· 720p | 按token | ¥35.88 | ¥21.00 | 约 ¥0.45/秒 | 约 ¥0.77/秒 | 约 ¥2.27 ~ ¥3.87 | 7.8 折 |
| doubao-seedance-2.0-pro-1080p | pro（满血）· 1080p | 按token | ¥39.78 | ¥23.25 | 约 ¥1.13/秒 | 约 ¥1.93/秒 | 约 ¥5.65 ~ ¥9.67 | 7.8 折 |
| doubao-seedance-2.0-pro-4k | pro（满血）· 4K | 按token | ¥20.28 | ¥12.00 | 约 ¥2.33/秒 | 约 ¥3.94/秒 | 约 ¥11.66 ~ ¥19.71 | 7.8 折 |
| doubao-seedance-2.5-720p | 2.5 · 720p | 按token | ¥56.00 | ¥33.60 | 约 ¥0.73/秒 | 约 ¥1.21/秒 | 约 ¥3.63 ~ ¥6.05 | 8 折 |
| doubao-seedance-2.5-1080p | 2.5 · 1080p | 按token | ¥61.60 | ¥36.80 | 约 ¥1.79/秒 | 约 ¥2.99/秒 | 约 ¥8.94 ~ ¥14.97 | 8 折 |

#### 💰 预扣冻结额度与最低测试充值参考（重要 · 避免余额不足报错）
| 模型 | 无视频预扣/秒 | 4秒预扣（最低门槛） | 5秒预扣 | 10秒预扣 | 5秒预计实扣（多退少补后） | 含参考视频 5秒预扣 | 首次测试建议充值 |
| seedance-2.0-mini-720p | ¥0.4658/秒 | ¥1.86 | ¥2.33 | ¥4.66 | 约 ¥1.12 | ¥1.42（¥0.2835/秒） | ¥5 即可测（4～10秒） |
| seedance-2.0-fast-720p | ¥1.0823/秒 | ¥4.33 | ¥5.41 | ¥10.82 | 约 ¥2.60 | ¥3.22（¥0.6435/秒） | ¥10 起（¥5 仅够测 4秒） |
| seedance-2.0-720p | ¥1.3041/秒 | ¥5.22 | ¥6.52 | ¥13.04 | 约 ¥3.13 | ¥3.97（¥0.7938/秒） | ¥10 起 |
| seedance-2.5-720p | ¥2.4500/秒 | ¥9.80 | ¥12.25 | ¥24.50 | 约 ¥5.30 | ¥7.35（¥1.4700/秒） | ¥15 ～ ¥25 |
| doubao-seedance-2.0-mini-480p | ¥0.4002/秒 | ¥1.60 | ¥2.00 | ¥4.00 | 约 ¥0.90 | ¥1.16（¥0.2310/秒） | ¥5 即可测（4～12秒） |
| doubao-seedance-2.0-mini-720p | ¥0.6003/秒 | ¥2.40 | ¥3.00 | ¥6.00 | 约 ¥1.44 | ¥1.73（¥0.3465/秒） | ¥5 即可测（4～8秒） |
| doubao-seedance-2.0-mini-1080p | ¥1.4790/秒 | ¥5.92 | ¥7.40 | ¥14.79 | 约 ¥3.59 | ¥4.26（¥0.8525/秒） | ¥10 起 |
| doubao-seedance-2.0-fast-480p | ¥0.7770/秒 | ¥3.11 | ¥3.89 | ¥7.77 | 约 ¥1.76 | ¥2.31（¥0.4620/秒） | ¥5 即可测（4～6秒） |
| doubao-seedance-2.0-fast-720p | ¥1.1655/秒 | ¥4.66 | ¥5.83 | ¥11.66 | 约 ¥2.80 | ¥3.47（¥0.6930/秒） | ¥10 起（¥5 仅够测 4秒） |
| doubao-seedance-2.0-fast-1080p | ¥2.8350/秒 | ¥11.34 | ¥14.18 | ¥28.35 | 约 ¥6.89 | ¥8.58（¥1.7150/秒） | ¥15 ～ ¥30 |
| doubao-seedance-2.0-pro-480p | ¥1.0764/秒 | ¥4.31 | ¥5.38 | ¥10.76 | 约 ¥2.43 | ¥3.15（¥0.6300/秒） | ¥10 起（¥5 仅够测 4秒） |
| doubao-seedance-2.0-pro-720p | ¥1.6146/秒 | ¥6.46 | ¥8.07 | ¥16.15 | 约 ¥3.87 | ¥4.73（¥0.9450/秒） | ¥10 ～ ¥15 |
| doubao-seedance-2.0-pro-1080p | ¥3.9780/秒 | ¥15.91 | ¥19.89 | ¥39.78 | 约 ¥9.67 | ¥11.63（¥2.3250/秒） | ¥20 ～ ¥40 |
| doubao-seedance-2.0-pro-4k | ¥4.4616/秒 | ¥17.85 | ¥22.31 | ¥44.62 | 约 ¥19.71 | ¥13.20（¥2.6400/秒） | ¥25 ～ ¥50 |
| doubao-seedance-2.5-720p | ¥2.8000/秒 | ¥11.20 | ¥14.00 | ¥28.00 | 约 ¥6.05 | ¥8.40（¥1.6800/秒） | ¥15 ～ ¥30 |
| doubao-seedance-2.5-1080p | ¥6.1600/秒 | ¥24.64 | ¥30.80 | ¥61.60 | 约 ¥14.97 | ¥18.40（¥3.6800/秒） | ¥35 ～ ¥65 |

### 接口信息
| 项 | 说明 |
| 提交端点 | POST /v1/videos 或 POST /v1/video/generations （标准 JSON，双端点完全等价兼容） |
| 轮询端点 | GET /v1/videos/{task_id} 或 GET /v1/video/generations/{task_id} |
| 视频直出预览 | GET /v1/videos/{task_id}/content （带 Bearer 令牌鉴权 302 重定向流式返回成片） |
| 下载成片 | 完成后响应里的 video_url （官方高速下载直链） |
| 鉴权方式 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Doubao （或 auto 智能路由分组） |

### 核心参数规范
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 模型名，如 seedance-2.5-720p 、 seedance-2.0-720p 、 seedance-2.0-fast-720p 、 doubao-seedance-2.0-mini-480p 等 |
| prompt | string | 是 | - | 画面 / 风格 / 动作描述。无我方硬性长度上限 |
| duration / seconds | integer / string | 是 | - | 视频输出时长（正整数秒）， 按 Token 计费视频必须显式传入秒数以计算预扣冻结上限 （不传或传 -1 会返回 400 参数错误）。 • 2.0 系列：传 4 – 15 ； • 2.5 系列：传 4 – 30 （视频编辑模式请传参考视频实际秒数） |
| ratio / aspect_ratio | string | 否 | adaptive / 16:9 | 画幅比例。支持 21:9 、 16:9 、 4:3 、 1:1 、 3:4 、 9:16 、 adaptive 。 • 重要修正 ：显式指定比例时（如 9:16 竖屏），模型将严格按该比例渲染，不再被参考图/参考视频强制改回横屏； • 未指定时，有参考素材默认 adaptive ，纯文生默认 16:9 |
| resolution | string | 否 | 依模型 | 视频分辨率， 480p / 720p / 1080p |
| images / image_urls | array | 否 | - | 参考图片数组。支持纯 URL 或 {url, role} 对象： • 1张默认 first_frame （首帧）； • 2张默认首尾帧 first_frame + last_frame ； • 3张及以上全量作为 reference_image ； • 也可使用单字段 image_url 、 first_image_url 、 last_image_url 、 reference_images |
| videos | array | 否 | - | 参考视频数组（ videos 或 reference_videos ），支持纯 URL 或 {url, role: "reference_video"} 。 • 2.0 限制 ≤3 段；2.5 限制 ≤10 段 |
| audios | array | 否 | - | 参考音频数组（ audios 或 reference_audios ），支持纯 URL 或 {url, role: "reference_audio"} 。 • 2.0 限制 ≤3 段且不能仅音频；2.5 限制 ≤10 段且可仅音频 |
| generate_audio | boolean | 否 | true | 是否生成原生同步音轨，本站默认开启 true |
| watermark | boolean | 否 | false | 视频水印开关，本站默认关闭 false （无水印） |
| camera_fixed | boolean | 否 | false | 锁定镜头开关，设为 true 可防止运镜漂移 |
| seed | integer | 否 | 随机 | 随机种子（用于复现画面效果） |
| return_last_frame | boolean | 否 | false | 是否在成片结果中额外返回尾帧图片（便于衔接下一段生成） |
| output_format | string | 否 | mp4 | 成片容器格式，可选 mp4 或 mov （推荐剪辑后期调色使用） |
| omni_reference_task_type | string | 否 | auto | 全模态任务意图： auto （自动推断）、 edit （视频编辑）、 extend （视频延长续写） |
| content | array | 否 | - | 官方原生多模态数组，若客户端已封装官方 content 结构，支持整包直通透传 |

### 提交方式与玩法自动切换
标准 JSON 请求。服务端根据传入的素材字段自动判定并路由最佳玩法：
| 玩法模式 | 触发方式 / 字段 | 说明 |
| 文生视频 (T2V) | 只传 prompt + duration | 纯文字驱动，严格尊重 aspect_ratio 画幅（默认 16:9） |
| 单图图生视频 (I2V) | 传 image_url 或 1 张 images | 单图首帧运镜动效化，可显式指定画幅或自适应 |
| 双图首尾帧过渡 | 传 first_image_url + last_image_url 或 2 张 images | 连接两张关键帧平滑生成过渡镜头 |
| 视频编辑 (V2V) | 传 videos 或 reference_videos | 在原视频画面基础上按提示词重新演绎风格与光影 |
| 全能多模态参考 | 组合传入 images + videos + audios | 综合多维素材，角色参考图片，动作跟随视频，节奏跟随音频 |
| 官方原生直通 | 传入 content 数组 | 客户端预构建的官方 content 多模态结构整包透传 |

### 示例请求
```
# 1. 标准调用格式（指定 12 秒 + 9:16 竖屏 + 生成原生音频）
# 💡 预扣提示：12 秒不带参考视频提交时需预扣 ¥12.99（完成后实扣约 ¥6.24，差额秒退）；小额测试建议改为 "duration": 4（预扣 ¥4.33）或 5（预扣 ¥5.41）
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast-720p",
    "prompt": "一只穿红大衣的小猫在雪地里抓雪花，电影微距",
    "duration": 12,
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "generate_audio": true
  }'

# 2. 图生视频（单图首帧，8 秒）
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast-720p",
    "prompt": "镜头缓慢平滑推进，光线逐渐变亮",
    "duration": 8,
    "aspect_ratio": "16:9",
    "image_url": "https://your-domain.com/start_frame.jpg"
  }'

# 3. 首尾帧平滑过渡（6 秒）
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini-720p",
    "prompt": "从白天的宁静城市平滑过渡到夜晚霓虹闪烁",
    "duration": 6,
    "first_image_url": "https://your-domain.com/day.jpg",
    "last_image_url": "https://your-domain.com/night.jpg"
  }'

# 4. 全能多模态参考（多图 + 参考视频 + 参考音频）
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast-720p",
    "prompt": "参考给定素材的风格与运镜动作生成",
    "duration": 10,
    "images": ["https://your-domain.com/char_1.jpg", "https://your-domain.com/char_2.jpg"],
    "videos": ["https://your-domain.com/camera_ref.mp4"],
    "audios": ["https://your-domain.com/bgm_ref.mp3"]
  }'

# 5. 原生 content 数组直通透传（官方格式）
curl -X POST https://api.oairegbox.cc/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-720p",
    "content": [
      {"type": "text", "text": "现代都市街道，细雨霏霏，电影质感"},
      {"type": "image_url", "image_url": {"url": "https://your-domain.com/ref.jpg"}, "role": "reference_image"}
    ],
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### 轮询取片与成片预览
```
# 1. 轮询任务状态（双端点兼容）
curl -sS https://api.oairegbox.cc/v1/videos/TASK_ID -H "Authorization: Bearer $TOKEN"

# 2. 成片下载（完成后响应中返回 video_url 官方直链）
curl -L "VIDEO_URL" -o result.mp4

# 3. 视频直出预览（支持网关流式直出）
curl -L -H "Authorization: Bearer $TOKEN" https://api.oairegbox.cc/v1/videos/TASK_ID/content -o preview.mp4
```

### Python 完整请求示例（全生命周期）
```
import time
import requests

BASE_URL = "https://api.oairegbox.cc"
API_KEY = "sk-你的令牌"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交视频生成任务（指定时长 12 秒 + 9:16 竖屏 + 开启原生音频）
payload = {
    "model": "seedance-2.0-fast-720p",
    "prompt": "一只穿红大衣的小猫在雪地里抓雪花，电影微距镜头，毛发飞雪细节生动",
    "duration": 12,
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "generate_audio": True
}

resp = requests.post(f"{BASE_URL}/v1/videos", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print(f"任务已提交，Task ID: {task_id}")

# 2. 轮询直到生成完毕
start_time = time.time()
while time.time() - start_time < 900:
    poll_res = requests.get(f"{BASE_URL}/v1/videos/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll_res.get("status")
    print(f"当前状态: {status} (耗时: {int(time.time() - start_time)}s)")
    if status == "completed":
        video_url = poll_res.get("video_url") or poll_res["data"][0]["url"]
        # 3. 下载保存成片
        content = requests.get(video_url, timeout=120).content
        with open("seedance_output.mp4", "wb") as f:
            f.write(content)
        print("成片已成功下载至本地 seedance_output.mp4！")
        break
    elif status in ("failed", "canceled"):
        raise RuntimeError(f"任务失败: {poll_res.get('error')}")
    time.sleep(5)
```

### 注意事项
- 时长与画幅严格生效 ：现已全面修复时长与画幅传递机制，传 duration: 12 即出真实 12 秒成片；显式传 aspect_ratio: "9:16" 严格出竖屏，不会被素材强制改为横屏。
- 音频与水印规范 ：本站默认开启原生同步音频（ generate_audio: true ），默认关闭水印（ watermark: false ，交付干净成品）。
- 双端点全面兼容 ：支持 /v1/videos 与 /v1/video/generations 双提交/轮询端点，支持 /content 视频直出预览。
- 多模态素材格式 ：参考图 / 参考音频除公网 URL 外，也支持 data:...;base64, 编码；官方 content[] 结构亦直接支持透传。

### 多模态输入 · 官方素材规格要求

#### 图片要求
| 项 | 要求 |
| 传入方式 | 公网 URL、Base64 Data URI |
| 图片格式 | jpeg、png、webp、bmp、tif、gif、heic、heif |
| 宽高比（宽/高） | (0.4, 2.5) |
| 边长（px） | (300, 6000) |
| 大小 | 单张图片 < 30MB；大文件建议使用公网直链 |
| 图片数量 | 首帧 1 张；首尾帧 2 张；参考图 2.0 支持 1–9 张，2.5 支持 1–30 张 |

#### 视频要求
| 项 | 要求 |
| 传入方式 | 公网视频 URL 或 Base64 Data URI |
| 视频格式 | mp4、mov（H.264/AVC、H.265/HEVC） |
| 分辨率 | 480p、720p、1080p（不超过请求档位） |
| 时长 | 单个视频 4–30 秒；2.0 最多 3 段，2.5 最多 10 段 |
| 大小 | 单个视频 ≤ 50MB |
| 帧率（FPS） | [24, 60] |

#### 音频要求
| 项 | 要求 |
| 传入方式 | 公网音频 URL、Base64 Data URI |
| 音频格式 | wav、mp3 |
| 时长 | 单个音频 2–30 秒；2.0 最多 3 段（需配合图片或视频），2.5 最多 10 段（允许仅音频） |
| 大小 | 单个音频 ≤ 15MB |

---

# Seedream 图像生成 Image
来源：https://docs.oairegbox.cc/#sec-seedream

## Seedream 图像生成 Image

### 模型与价格
| 模型 | 版本 | 定位 | 计费方式 | 价格 (7折特惠) | 尺寸与档位说明 |
| doubao-seedream-5-0-pro | 5.0 Pro | 旗舰画质，官方最新 | 按张 (按分辨率阶梯) | 1K 档：¥0.225/张 2K 档：¥0.495/张 4K 档：¥0.495/张 | 传入 size 自动识别计费，无需切换模型名： • ≤ 261万像素（如 1024x1024, 1920x1080）：¥0.225 • > 261万像素（如 2048x2048, 2K, 4K）：¥0.495 |
| doubao-seedream-5-0 | 5.0 | 新版，画质强、性价比最高 | 按张 | ¥0.24/张 | 基础版支持到 4096×4096 |
| doubao-seedream-4-5 | 4.5 | 稳定成熟档 | 按张 | ¥0.25/张 | 基础版支持到 4096×4096 |

### 接口信息
| 项 | 说明 |
| 文生图 | POST /v1/images/generations （ 同步 ，返回即出图） |
| 图生图 / 编辑 | 同 /v1/images/generations （带 image 字段）或 /v1/images/edits |
| 返回 | data[0].url （默认）或 data[0].b64_json |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Doubao |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 上表三个之一 |
| prompt | string | 是 | - | 图像描述提示词。无我方硬性长度上限（走火山官方） |
| size | string | 否 | 1024x1024 | 图像生成尺寸规格，支持两种格式： 1. 像素规格（推荐）： "1024x1024" (1K 档)、 "2048x2048" (2K 档)、 "3840x2160" (4K 档)、 "2560x1440" 等； 2. 档位别名： "2K" 、 "4K" ； （计费阶梯：总像素 ≤ 261 万归入 1K 基准档按 ¥0.21 收费；> 261 万归入高清档按 ¥0.42 收费） |
| response_format | string | 否 | url | url （图片直链）或 b64_json （base64 内嵌） |
| image | string / array | 否 | - | 参考图（图生图 / 编辑 / 多图融合）：单张字符串、多张数组。 填了 image 即进入编辑 ；"二次编辑" = 把上一轮 产图 URL 回传继续改，可反复迭代。 参考图最多 14 张，参考图 + 产图合计 ≤ 15 。元素为 公网 URL 或 Base64 （ data:image/png;base64,... ） |
| sequential_image_generation | string | 否 | disabled | 组图模式 ：设 "auto" 让模型一次连续生成 一组相关图 （组图， data 返回多张）。产图 + 参考图合计 ≤ 15 张 |
| n | integer | 否 | 1 | ⚠️ 本线路 n 每次仅返回 1 张 ，请保持 n=1 ； n>1 会按 n 计费但仍只返回 1 张。 要一次一组相关图请用上面的 sequential_image_generation:"auto" 组图 |
分辨率范围与档位说明（实测）：
| 模型 | 最高输出 | 最低 | 说明 |
| doubao-seedream-4-5 | 4096×4096 （真 4K） | 约 1920×1920 | 基础版支持到 4K |
| doubao-seedream-5-0 | 4096×4096 （真 4K） | 约 1920×1920 | 基础版支持到 4K |
| doubao-seedream-5-0-pro | 4K（3840×2160 / 4096×4096） | 1024×1024 | 全面支持 1K、2K、4K，按请求 size 像素智能阶梯计费 |

### 提交方式
JSON（同步）。 image 字段传单张字符串或多张数组即进入图生图 / 多图融合；参考图支持 URL / 多图 / Base64 三种 （已实测）。加 "response_format":"b64_json" 可拿 base64 内嵌。
| 能力 | 支持 | 说明 |
| URL 参考图 | ✅ | 公网 http/https 直链 |
| 多图融合 | ✅ | image 传数组，参考图最多 14 张 （参考图 + 产图 ≤ 15） |
| Base64 参考图 | ✅ | data:image/png;base64,... （带前缀） |
| 单张大小 | ≤ 10 MB | 4.5 档服务上限 15MB，建议统一 ≤10MB |
| 格式 | JPEG / PNG | 5.0 档另支持 webp/bmp/tiff/gif；建议优先 JPEG/PNG |
| 输入图尺寸 | 单边 ≤ 4096 | 宽高比约 [1/3, 3] |

### 示例请求
```
# 1. 默认 1K 标清生成（¥0.21 / 张）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "一只可爱的金毛幼犬在阳光草坪上奔跑，微距写实摄影",
    "size": "1024x1024"
  }'

# 2. 2K 高清生成（¥0.42 / 张）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "电影感雪山日出全景，光影通透细腻，壁纸级质感",
    "size": "2048x2048"
  }'

# 3. 16:9 宽画幅高清生成（2560x1440，¥0.42 / 张）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "电影感雪山日出全景，宽画幅",
    "size": "2560x1440"
  }'

# 4. 图生图：单张参考图（URL）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-4-5",
    "prompt": "把背景换成落日海边",
    "size": "2048x2048",
    "image": "https://example.com/ref.jpg"
  }'

# 5. 多图融合：image 传数组（参考图最多 14 张，参考图 + 产图 ≤ 15）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "把这两张融合成一张海报",
    "size": "2048x2048",
    "image": ["https://example.com/a.jpg", "https://example.com/b.jpg"]
  }'

# 6. 编辑 / 二次编辑（5.0 Pro）：编辑与文生图同一接口，多带 image 字段（填上一轮产图的 URL）；可反复迭代
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "给这只柴犬戴上一顶红色圣诞帽，狗和纯白背景保持不变",
    "image": "https://<上一轮产图URL>",
    "size": "2048x2048"
  }'

# 7. 组图（5.0 Pro）：sequential_image_generation=auto，一次连续生成一组相关图（产图 + 参考图 ≤ 15）
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "柴犬的圣诞四联漫画，风格一致",
    "sequential_image_generation": "auto",
    "size": "2048x2048"
  }'

# 8. 返回 base64
curl -X POST https://api.oairegbox.cc/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "doubao-seedream-4-5",
    "prompt": "极简红色圆形，纯白背景",
    "size": "2048x2048",
    "response_format": "b64_json"
  }'
```

### 轮询取片
同步接口，无需轮询 ：请求返回即拿到结果。默认 data[0].url 为可直接下载 / 内嵌的图片直链（有有效期，请及时保存）；需 base64 内嵌时加 "response_format":"b64_json" 取 data[0].b64_json 。
```
# 默认 url 返回结构：
# {"created":1786957747,"data":[{"url":"https://<官方签名直链>/xxx.jpeg"}]}
curl -L "IMAGE_URL" -o result.jpeg
```

### Python 完整请求

#### 1. 标准 OpenAI SDK 调用（推荐）
```
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://api.oairegbox.cc/v1"
)

# 生成 2K 高清图像（系统自动按 2K 档位 ¥0.42 计费）
response = client.images.generate(
    model="doubao-seedream-5-0-pro",
    prompt="超写实未来赛博朋克城市雨夜，霓虹倒影，电影质感",
    size="2048x2048",
    response_format="url"
)

print("生成成功，图片直链:", response.data[0].url)
```

#### 2. requests 库原生调用
```
import requests

BASE = "https://api.oairegbox.cc/v1"
H = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "doubao-seedream-5-0-pro",
    "prompt": "一只橘猫坐在窗台上，午后阳光洒落，超写实摄影",
    "size": "1024x1024",
}).json()

url = r["data"][0]["url"]
open("seedream.jpeg", "wb").write(requests.get(url).content)
```

### 注意事项
- doubao-seedream-5-0-pro 智能阶梯计费 ：无需切换模型名，总像素 ≤ 261 万（如 1024x1024 , 1920x1080 ）按 1K 档 ¥0.225/张 计费；> 261 万（如 2048x2048 , 2560x1440 , 3840x2160 , 2K , 4K ）按高清档 ¥0.495/张 计费。
- 编辑 / 二次编辑 ：与文生图 同一接口 /v1/images/generations ，多带 image 字段（填参考图或 上一轮产图 URL ）即进入编辑；产图 URL 可反复回传迭代。
- 本线路 n=1 每次 1 张； 要一次一组相关图 用 sequential_image_generation:"auto" （组图， data 多张，产图 + 参考图 ≤ 15）。
- 参考图 ≤10MB、JPEG/PNG、单边 ≤4096、 最多 14 张（参考图 + 产图 ≤ 15） ；非法参考图返回 400 不计费。输出格式 JPEG。

### 建议
- 旗舰首选 doubao-seedream-5-0-pro ：官方最新架构，支持 1K 到 4K 全画幅；高性价比日常出图可选 5-0 。
- 16:9 推荐 2560x1440 或 3840x2160 、9:16 推荐 1440x2560 或 2160x3840 、1:1 推荐 1024x1024 或 2048x2048 。
- 多图融合把主体图放前、风格图放后，提示词点明"融合成一张"。

---

# Qwen 图像生成（通义千问） Image
来源：https://docs.oairegbox.cc/#sec-qwen-image

## Qwen 图像生成（通义千问） Image

### 模型与价格
| 模型 | 分辨率档位 | 定位 | 计费 | 价格 / 张 |
| qwen-image-3.0-pro | 1K（默认 / ≤261万像素） | 通义千问图像 3.0 Pro，高画质文生图 + 图生图 / 编辑 | 按张 | ¥0.25 |
| qwen-image-3.0-pro | 2K（长边 ≥2000 或 >261万像素） | 通义千问图像 3.0 Pro，2K 高清出图 | 按张 | ¥0.50 |

### 接口信息
| 项 | 说明 |
| 文生图 | POST /v1/images/generations （ 同步 ，返回即出图） |
| 图生图 / 编辑 | POST /v1/images/edits （传参考图 image + prompt ，在原图上编辑）； 同模型、同档位同价（1K ¥0.25 / 2K ¥0.50） |
| 返回 | data[0].url （默认，阿里官方直链）或 data[0].b64_json |
| 鉴权 | Authorization: Bearer sk-你的令牌 |
| 令牌分组 | Wan 或 auto （智能路由） |

### 核心参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| model | string | 是 | - | 固定 qwen-image-3.0-pro |
| prompt | string | 是 | - | 图像描述提示词（中英文均可） |
| size | string | 否 | 2528x1696 | 宽×高，如 1024x1024 。 精确生效 （实测按传入 WxH 原样出图）； 不传默认约 2528×1696 （≈3:2）。 画幅只认 size |
| aspect_ratio | string | — | — | ⚠️ 本模型不生效 （会被忽略、仍出默认画幅）。要控画幅请用 size |
| response_format | string | 否 | url | url （阿里官方图片直链）或 b64_json （base64 内嵌，已实测） |
| n | integer | 否 | 1 | 每次返回 1 张，保持 n=1 ；需多张请多次调用 |
| image | string | 否 | - | 图生图 / 编辑 （打 /v1/images/edits ）：参考图，公网 URL 或 base64（ data:image/...;base64, ）或 multipart 文件（ -F "image=@ref.png" ）。实测参考图会被 忠实读取 （原图保留 + 按 prompt 编辑） |

### 示例请求
```
# 文生图 —— 同步，一次返回即拿到图片（无需轮询）
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0-pro","prompt":"一只柯基犬坐在草地上，午后阳光，超写实摄影"}'

# 指定画幅：1:1（用 size，别用 aspect_ratio）
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0-pro","prompt":"国潮工笔锦鲤，红金配色","size":"1328x1328"}'

# 16:9 宽画幅
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0-pro","prompt":"电影感雪山日出全景","size":"1664x928"}'

# 返回 base64
curl -X POST https://YOUR_BASE/v1/images/generations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0-pro","prompt":"极简红色圆形，纯白背景","size":"1024x1024","response_format":"b64_json"}'

# 图生图 / 编辑 —— 传参考图打 /v1/images/edits（同模型、同档位同价 1K ¥0.25 / 2K ¥0.50，参考图不额外计费）
curl -X POST https://YOUR_BASE/v1/images/edits \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0-pro","prompt":"保留主体，把背景换成落日海边","image":"https://example.com/ref.jpg"}'

# 图生图 —— 也可用文件上传参考图（multipart）
curl -X POST https://YOUR_BASE/v1/images/edits \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=qwen-image-3.0-pro" -F "prompt=把它变成柯基脸，保持白色背景" -F "image=@ref.png"
```

### 轮询取片
同步接口，无需轮询 ：请求返回即拿到结果。默认 data[0].url 为阿里官方图片直链（有有效期，请及时保存）；需 base64 内嵌时加 "response_format":"b64_json" 取 data[0].b64_json 。
```
# 默认 url 返回结构：
# {"created":1786957747,"data":[{"url":"https://dashscope-<...>.aliyuncs.com/xxx.png"}]}
curl -L "IMAGE_URL" -o result.png
```

### Python 完整请求
```
import requests
BASE = "https://YOUR_BASE/v1"
H = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}
r = requests.post(f"{BASE}/images/generations", headers=H, json={
    "model": "qwen-image-3.0-pro",
    "prompt": "一只柯基犬坐在草地上，午后阳光，超写实摄影",
    "size": "1328x1328",
}).json()
url = r["data"][0]["url"]
open("qwen.png", "wb").write(requests.get(url).content)
```

### 注意事项
- 文生图 ：给 prompt （可加 size ）打 /v1/images/generations 。 图生图 / 编辑 ：传参考图 image 打 /v1/images/edits ， 同模型、同档位同价（1K ¥0.25 / 2K ¥0.50） ，参考图不额外计费。
- 画幅只认 size （精确 WxH）； aspect_ratio 会被忽略、仍出默认约 2528×1696 。
- n=1 每次 1 张；需多张请多次调用。
- 返回 阿里官方图片直链 （ *.aliyuncs.com ）、 无水印 ；链接有有效期，请及时下载保存。输出 PNG 。

### 建议
- 要指定比例就传 size ：1:1 1328x1328 、16:9 1664x928 、9:16 928x1664 ；不在意画幅可不传（默认约 2528×1696）。
- 需要本地落库用 "response_format":"b64_json" ，否则默认拿直链最省事。

---

# Meta Muse 全模态工作台（ muse-fast 分组）
来源：https://docs.oairegbox.cc/#sec-muse

## Meta Muse 全模态工作台（ muse-fast 分组）
Meta Muse（Endo / Hatch） 是一套基于专属云端沙盒 VM 的全模态 AI 引擎。本平台通过独立分组 muse-fast （同时已纳入 auto 自动分组）提供全套 16 款模型：涵盖 云端自主全能智能体（ muse-agent ）、标准文本与多模态对话（ muse-chat ）、原生 2K 级 AI 绘图与参考图编辑、原生 720p HD 有声视频生成（10s/20s/30s/40s/50s/60s 全档长视频与智能续写，支持 mute_voice 人物静音控制）、AI 漫剧/短剧导演智能体（ muse-director ）、AI 多音色播客生成（Podcast）、邀请码自动核销助力（Invite）、Avocado v2 超拟真语音合成（TTS）、极速语音识别转写（ASR）、语音对话（Audio Chat）以及全双工实时语音流（Live Voice） ，并支持独家的 云端沙盒会话粘性（Session Stickiness） 。所有图像与视频均 原样返回 Muse AI 原生输出规格，不做本地或服务端超分放大与抠图处理 。

### 一、模型矩阵与价格
| 模型 ID | 模态能力 | 推荐端点 | 计费方式 | 价格 / 倍率 | 核心特性说明 |
| muse-chat 可选: muse-willow | 标准文本 / 图文对话 / 工具调用 / 深度推理 | POST /v1/chat/completions | 按量 (Token) | 输入 ¥2.00/M （1.0x）· 输出 ¥8.00/M （4.0x） | 原生 350K（350,000 Tokens）超长上下文 ；支持 OpenAI tools / tool_choice 标准工具调用（Function Calling） 、5 档深度推理调节（ reasoning_effort : low ~ max ）、多模态识图、联网搜索与会话粘性（传 muse-willow 可切换 Willow 模型） |
| muse-agent 别名: muse-spark / muse-bot | 云端自主全能 Agent（代码 + 生图 + 生视频 + 播客 + 自动上传） | POST /v1/chat/completions | 按量 (Token) + 产出媒体折算 | 输入 ¥4.00/M （2.0x）· 输出 ¥16.00/M （8.0x） 含媒体时自动折算 Token（图 ¥0.10 / 视频 ¥0.30） | 完整开放云端 Linux VM 沙盒执行权限、 media.generate_image 、 media.generate_video 、 ffmpeg 剪辑拼接与 remote-storage upload-file ，支持在单轮对话中自主规划、编写网页/脚本、生成多镜漫剧并输出 https://muse.ai/files/... 直链 |
| muse-image | 文生图 / 参考图编辑 | POST /v1/images/generations POST /v1/images/edits | 按次 | ¥0.03 / 张 | 原样返回 Muse AI 原生最高 2K 级高清图像；支持画幅比例、风格、负向提示词、最多 4 张参考图、格式转换与异步轮询（不做超分与本地抠图） |
| muse-video | 文生视频 / 首尾帧 / 多参考图（≤10 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥0.30 / 个 | 原样输出单段 1~10 秒原生 720p HD 24fps 有声无水印 MP4；支持画幅比例、时长裁剪、镜头运动（ camera_motion ）、首尾帧及参考图驱动（不做超分缩放） |
| muse-video-20s | 20 秒长视频 / 视频续写（成片总长 ≤20 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥0.50 / 个 | 两段原生 720p HD 24fps 末帧接力无缝拼接；传入 video_url 时在源视频末尾续写， 成片总长（源视频 + 续写）≤20 秒 ；源视频须短于 19 秒 |
| muse-video-30s | 30 秒长视频 / 视频续写（成片总长 ≤30 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥0.60 / 个 | 三段原生 720p HD 24fps 末帧接力无缝拼接；传入 video_url 时在源视频末尾续写， 成片总长（源视频 + 续写）≤30 秒 ；源视频须短于 29 秒 |
| muse-video-40s | 40 秒长视频 / 视频续写（成片总长 ≤40 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥0.80 / 个 | 四段原生 720p HD 24fps 末帧接力无缝拼接；传入 video_url 时在源视频末尾续写， 成片总长（源视频 + 续写）≤40 秒 ；源视频须短于 39 秒 |
| muse-video-50s | 50 秒长视频 / 视频续写（成片总长 ≤50 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥1.00 / 个 | 五段原生 720p HD 24fps 末帧接力无缝拼接；传入 video_url 时在源视频末尾续写， 成片总长（源视频 + 续写）≤50 秒 ；源视频须短于 49 秒 |
| muse-video-60s | 60 秒长视频 / 视频续写（成片总长 ≤60 秒） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥1.20 / 个 | 六段原生 720p HD 24fps 末帧接力无缝拼接；传入 video_url 时在源视频末尾续写， 成片总长（源视频 + 续写）≤60 秒 ；源视频须短于 59 秒 |
| muse-director 别名: muse-drama / muse-manju / muse-video-pro | AI 漫剧 / 短剧智能导演（剧本自动分镜 + 设定图 + 拼接成片） | POST /v1/videos GET /v1/videos/{task_id} | 按实际产出动态结算 | 过程生图 ¥0.03 / 张 + 成片时长 ¥0.02 / 秒 | 传入剧本文件（ .md/.txt/.json/.yaml/.srt 或 script 文本）与角色/场景设定图，云端导演 Agent 自动完成自然剧情节拍切分（非固定10秒整、每段1–2个长镜头、换视频强制切机位）、彩色导演分镜符生成、内置角色音色锁定（或 mute_voice=true 人物静音）与无缝拼接，按清单 img{I}_vid{V}_sec{S}_{slug}.mp4 精确计费 |
| muse-podcast | AI 多音色播客生成（MP3） | POST /v1/videos GET /v1/videos/{task_id} | 按次 | ¥0.30 / 期 | 自动调研撰稿并用 Avocado v2 多音色合成双人/多人对谈 MP3，支持 prompt 、 language 、 seconds / minutes 、 speakers / voices ；音频地址在 video_url / url 字段 |
| muse-invite | 邀请码自动填写助力 | POST /v1/chat/completions | 按次 | ¥0.09 / 次 | 传入邀请码或邀请链接，自动分配未填码新号核销助力（双方各获 +10 亿 Tokens）；已用号永久防重，若邀请码无效或邀请人达上限自动恢复状态且不扣费 |
| muse-tts | Avocado v2 神经网络语音合成 | POST /v1/audio/speech POST /v1/chat/completions | 按次 | ¥0.02 / 次 | 支持 alloy (Aria)、 nova 、 echo (Helio)、 fable (Bud) 等高自然度音色，输出 MP3/WAV/OPUS/PCM |
| muse-asr | 极速语音识别转写 (STT/ASR) | POST /v1/audio/transcriptions | 按次 | ¥0.02 / 次 | 兼容 MP3 / WAV / OGG / M4A / FLAC / WebM / PCM，云端沙盒秒级精准转写 |
| muse-audio | 多模态语音输入 & 语音回复 | POST /v1/chat/completions | 按量 (Token) | 输入 ¥5.00/M （2.5x）· 输出 ¥20.00/M （10.0x） | 支持传入 input_audio 语音提问，同步返回文本回答 + Avocado v2 合成语音直链与 Base64 |
| muse-live | 全双工实时语音流 / 虚拟人通话 | WS /v1/realtime?model=muse-live POST /v1/chat/completions | 按量 (Token) | 输入 ¥5.00/M （2.5x）· 输出 ¥20.00/M （10.0x） | 支持 OpenAI Realtime 风格 WebSocket 双向语音流及原生虚拟人通话信令 |

#### 1.1 文本与多模态对话参数（ muse-chat / muse-agent / muse-willow ）
通过标准 OpenAI POST /v1/chat/completions 调用，原生具备 350,000 Tokens（350K）超长上下文窗口 ，并完整兼容 OpenAI tools 函数调用协议与 5 档推理深度调节：
| 参数名 | 类型 | 必选 | 可选值 / 说明 |
| model | string | 是 | "muse-chat" （默认 Auto 路由模型）、 "muse-willow" （切换新一代 Willow 模型）或 "muse-agent" / "muse-spark" （全能云端沙盒 Agent） |
| messages | array | 是 | OpenAI 标准消息数组（支持 system / user / assistant / tool 角色及 image_url 多模态识图，单次上下文最高 350K Tokens ） |
| reasoning_effort / thinking_level | string | 否 | 5 档思考深度调节： "low" 、 "medium" 、 "high" （默认）、 "xhigh" （超强推理）、 "max" （满血极限推理） |
| tools / tool_choice | array / any | 否 | 标准 OpenAI Function Calling ：支持传入客户端函数 Schema 数组，以及 "auto" 、 "none" 、 "required" 或指定函数对象；命中时返回标准 finish_reason: "tool_calls" 与 message.tool_calls （同时支持流式 SSE delta.tool_calls 与非流式） |
| in_reply_to / reply_to_target | string / object | 否 | 多轮对话中指定引用历史消息 ID 或历史生成图片（ {"message_id": "...", "image_id": "..."} ）进行定向追问或修改 |

### 二、图像生成与编辑参数（ muse-image ）
既可调用标准 POST /v1/images/generations （JSON）、 POST /v1/images/edits （multipart 表单），也可直接通过 POST /v1/chat/completions 指定 "model": "muse-image" 生成。 平台原样返回 Muse AI 原生生成的图像像素（原生最高 2K 级），不做任何插值超分或本地抠图处理。
| 参数名 | 类型 | 必选 | 可选值 / 说明 |
| model | string | 是 | 固定传 "muse-image" |
| prompt | string | 是 | 图像画面描述提示词（支持中英文） |
| size / aspect_ratio / ratio | string | 否 | 画幅比例控制： "1:1" （原生约 1600×1600 ）、 "16:9" （原生 2048×1152 ）、 "9:16" （原生 1152×2048 ）、 "4:3" 、 "3:4" 、 "3:2" 、 "2:3" ；按 Muse AI 原生生成尺寸直出，不做后处理超分放大 |
| style | string | 否 | 视觉风格指令，如 "photorealistic" 、 "anime" 、 "cinematic" 、 "3d" 、 "vivid" 、 "natural" |
| negative_prompt | string | 否 | 负向提示词（画面中需避免的元素） |
| seed | integer | 否 | 随机种子（用于风格与构图复现） |
| image / images / reference_images | string / array | 否 | 参考图（最多 4 张），支持公网 https:// URL、 data:image/png;base64,... 或裸 Base64 |
| n | integer | 否 | 生成张数（ 1 – 4 ，默认 1 ） |
| output_format | string | 否 | 可选 "png" / "jpeg" / "webp" （保持 1:1 原生像素无损转换容器格式；默认直出原生 WebP；不支持 background="transparent" 抠图） |
| response_format | string | 否 | "url" （默认，返回图片直链）或 "b64_json" （返回 Base64） |
| async | boolean | 否 | 传 true 时转为后台异步任务，通过 GET /v1/images/generations/{task_id} 轮询 |

### 三、视频生成、长视频续写与漫剧导演参数（ muse-video / 20s~60s / muse-director ）
支持异步任务接口 POST /v1/videos （兼容 JSON 与 multipart/form-data 上传首帧图），提交后轮询 GET /v1/videos/{task_id} ；完成后直接从 video_url （或 data[0].url / GET /v1/videos/{task_id}/content ）获取 MP4 成片。 平台原样返回 Muse AI 原生 720p HD（24fps）有声视频流，不做服务端超分缩放。
| 参数名 | 类型 | 必选 | 可选值 / 说明 |
| model | string | 是 | 七档可选： "muse-video" （单段 ≤10 秒， ¥0.30/个 ）、 "muse-video-20s" （20 秒， ¥0.50/个 ）、 "muse-video-30s" （30 秒， ¥0.60/个 ）、 "muse-video-40s" / "muse-video-50s" / "muse-video-60s" （40/50/60 秒， ¥0.80 / 1.00 / 1.20 /个 ），以及智能漫剧导演模型 "muse-director" （别名 "muse-drama" / "muse-manju" / "muse-video-pro" ，过程生图 ¥0.03/张 + 成片秒数 ¥0.02/秒 ） |
| prompt | string | 是 | 视频镜头、动作与光影描述提示词 |
| size / aspect_ratio / ratio | string | 否 | 视频画幅比例： "16:9" （横屏，原生 1280×720 / 1248×704 ）、 "9:16" （竖屏，原生 704×1248 ）、 "1:1" 、 "4:3" 、 "3:4" ；固定按 Muse AI 原生 720p HD 24fps 直出 |
| seconds | string | 否 | ⚠️ 在 /v1/videos 接口中 seconds 建议传字符串 （如 "5" 、 "8" 、 "10" ，传整数在 OpenAI Video 协议层可能报类型错误）； muse-video 支持 1~10 秒无损裁剪（超过 10 秒或传 video_url 续写请改用 muse-video-20s ~ muse-video-60s ，否则返回 400）。 续写模式（传了 video_url ）下， seconds 表示成片总时长（源视频 + 续写部分），不是续写秒数 ：不传则默认补到档位上限（20s 档补到 20 秒、30s 档补到 30 秒）；可传小于上限的值，但须比源视频长至少 1 秒；超过档位上限返回 400。例：6.04 秒源视频 + muse-video-20s + seconds: "20" → 平台自动续写约 13.96 秒，成片 20 秒。 |
| camera_motion / motion | string | 否 | 运镜方式，如 "pan_left" 、 "zoom_in" 、 "orbit" 、 "tracking_shot" 、 "static" |
| resume_task_id / session_id 或调 POST /v1/videos/{task_id}/remix | string | 否 | 失败或未完成任务断点续作（适用于 muse-video / 20s~60s / muse-director ） ：当某笔长视频或漫剧任务因最后 1~2 段遇到模型报错而中断时，传入原任务的 session_id （从错误消息 on session <UUID> 或任务详情 session_id 获取）或原 task_id ，系统将 严格锁定原云端 VM 沙盒与原会话上下文 ，直接复用已生成的 seg_XX.mp4 分段，仅补齐缺失分段并完成拼接上传，无需从头重跑！ |
| style_preset 兼容: style | string | 否 | 视觉画风预设（全系视频模型通用，支持三选一模式） ： • 不选 / 传 "none" （或 "raw" / "off" ） ：不附加任何内置画风提示词，100% 由用户自己的 prompt 与参考图决定风格； • 选内置画风 ID（共 8 款，支持中英文别名） ： "cinematic_realistic" （好莱坞真人实拍，别名 "realistic" / "live_action" / "真人" ）、 "2d_anime" （2D 日漫/国漫赛璐璐，别名 "anime" / "2d" / "动漫" ）、 "3d_xianxia" （UE5 高清 3D 国漫修仙，别名 "3d" / "xianxia" / "修仙" ）、 "american_comic" （欧美暗黑漫画，别名 "cartoon" / "comic" / "美漫" ）、 "cyberpunk_neon" / "cyberpunk_noir" （赛博朋克霓虹暗黑，别名 "cyberpunk" / "scifi" / "赛博朋克" ）、 "dark_ink_wuxia" （东方水墨武侠电影，别名 "ink" / "wuxia" / "水墨" ）、 "ecommerce_ugc" （电商带货/真人种草，别名 "ugc" / "ecommerce" / "电商" ）； • 直接传自定义画风文本 ：若传入非预设 ID 的任意描述文本，系统自动作为 [Custom Visual Style] 注入。 |
| custom_style | string | 否 | 用户自定义画风补充指令 ：可单独使用，也可与 style_preset 叠加使用（例如选了 style_preset: "2d_anime" 后再用 custom_style 追加特定光影/色调要求）。 |
| skill_preset 别名: skills / transition_skill | string / array | 否 | 电影学运镜与开源导演技能库预设（支持单选、逗号多选组合如 "occlusion_wipe,micro_drama_hook" 、传 "none" 关闭或直接传自定义文本） ： • 传 "none" / "raw" / "off" ：关闭内置技能注入，100% 按用户原始提示词执行； • 9 大经典电影学运镜与转场技能 ID ： ① "occlusion_wipe" （前景遮挡无缝转场，别名 "wipe" / "遮挡转场" ） · ② "cut_on_action" （动接动硬切+30°景别切换，别名 "动接动" ） · ③ "match_cut" （图形/动作相似性匹配转场） · ④ "whip_pan" / "whip_pan_match" （极速甩镜动量转场，别名 "甩镜" ） · ⑤ "dolly_zoom_oner" （希区柯克变焦与推轨一镜到底，别名 "oner" / "一镜到底" ） · ⑥ "over_shoulder_axis" / "ots_dialogue" （180度轴线正反打与越肩调度，别名 "ots" / "正反打" ） · ⑦ "rack_focus_mood" （浅景深虚实变焦与空镜留白，别名 "移焦" ） · ⑧ "action_choreography" （高燃动作博弈与受击物理反馈，别名 "fight" / "打斗" ） · ⑨ "dutch_angle_thriller" （荷兰角悬疑压迫与明暗惊悚，别名 "thriller" / "悬疑" ）； • 7 大开源影视/漫剧/TVC 专项导演技能 ID（详见 3.2 与 3.3 节） ： ⑩ "manju_director" （漫剧全流程导演技能包 v2.2，别名 "director" / "漫剧导演" ） · ⑪ "micro_drama_hook" （短剧黄金 3 秒冲突钩子与付费卡点，别名 "hook" ） · ⑫ "emotion_micro_acting" （潜台词微表情与呼吸落点表演，别名 "micro_acting" ） · ⑬ "xianxia_speed_ramp" （东方仙侠变速运镜与法术物理因果链，别名 "speed_ramp" ） · ⑭ "tvc_product_hero" （商业 TVC 产品受力因果链与微距质感，别名 "tvc" ） · ⑮ "auteur_wong_kar_wai" （王家卫式抽帧霓虹与前景框景美学，别名 "wong_kar_wai" ） · ⑯ "spatial_blocking_continuity" （三维空间走位锁与左右手/道具连戏，别名 "blocking" ）。 |
| custom_skill | string | 否 | 用户自定义电影学运镜 / 分镜 / 转场规则 ：用户可自由编写任意导演调度、转场衔接或镜头语言要求（可单独使用，或与 skill_preset 叠加生效）。 |
| negative_prompt | string | 否 | 负向提示词（需排除的瑕疵或元素） |
| seed | integer | 否 | 随机种子 |
| image / first_frame / input_reference | string / file | 否 | 首帧参考图（支持 URL、Data URL 或 multipart 文件上传） |
| last_frame / last_frame_url | string | 否 | 尾帧参考图（首尾帧过渡控制） |
| images / reference_images | array | 否 | 多参考图列表（最多 4 张 URL 或 Base64） |
| video_url | string | 否 | 源视频公网 MP4 URL 或 data:video/mp4;base64,... （ 仅限 muse-video-20s / muse-video-30s ）：从源视频最后一帧接着无缝续写，成片 = 源视频 + 续写部分（不支持改风格 restyle）。 源视频时长要求 ：须比目标成片总时长短至少 1 秒—— muse-video-20s 建议源视频 ≤18 秒， muse-video-30s 建议 ≤28 秒，40s/50s/60s 档依此类推（比档位总时长短 2 秒以上）；源视频无法解析或已达到目标总时长会直接返回 400（不扣费）。 |
| mute_voice 别名: mute_speech / mute_character / silent_speech | boolean | 否 | 人物是否静音 / 禁配音控制（默认 false ， muse-video 全系与 muse-director 通用） ： • 默认 false （人物正常发音）：角色按提示词或剧本台词正常开口说话配音； • 传 true （人物静音）： 画面中人物依然配合台词与情绪正常张嘴做口型表演（方便后期贴配音），但音频轨中人物完全静音不发声（解决部分语种原生配音效果不佳问题） ，同时完整保留电影级环境音效（SFX）、动作拟音（Foley）与背景氛围音乐（BGM）。 |
| script / script_url / files / documents | string / array / file | 否 | muse-director 专属剧本与资产输入 ：支持直接传 script 剧本文本、 script_url 远程剧本链接、 storyboard （分镜表 JSON/文本）、 character_bible （人设圣经），或通过 multipart/form-data 上传 .md / .txt / .json / .yaml / .srt 剧本文件及多张角色设定图 / 彩色导演分镜符图（最多 6 张参考图）。 |
| use_proxy | boolean | 否 | 下载链接模式控制（默认 false ） ： • 默认 false ：任务完成后自动上传发布至 Meta Muse 官方 CDN，主字段 url / share_url 直接返回 https://muse.ai/files/... 官方免登录共享直链（有效期 48 小时） ，包括 muse-video 、 muse-video-20s/30s 拼接长视频、 muse-podcast 与 muse-image ； • 传 true （或在轮询 GET /v1/videos/{task_id}?proxy=1 时附带 proxy=1 ）：主字段优先返回本平台预热的 6 小时高速缓存直链（同时始终在 proxy_url 字段与 GET /v1/videos/{task_id}/content 端点提供服务器代下流）。 |

#### 3.1 内置视觉画风库（ style_preset ）完整提示词与统一剧本 30 秒横向对比样片
您可以通过 GET /v1/videos/presets 实时查询以下全部内置画风与电影学技能定义。若不想使用任何内置风格，传 "style_preset": "none" 即可；若需自定义，传 "custom_style": "您的风格描述" ：
| style_preset 值 | 风格名称与适用场景 | 系统实际注入的完整内置提示词（Built-in Prompt） | 30秒同剧本对比样片（打开后异步逐个加载 · 主备自动容灾 · 永久不清除） |
| "none" | 不注入内置风格（原样直传 / Raw） 不附加任何内置画风提示词，100% 由用户自己的 prompt 与参考图决定画面风格。 | （空 · 不注入任何额外画风提示词，100% 原样直传用户 prompt） | ⏳ 等待异步加载… ⏱ 30.0s · 18.7 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "cinematic_realistic" | 好莱坞真人实拍电影感（Cinematic Realistic） 35mm 变形宽银幕电影镜头、真实皮肤毛孔与织物纹理、自然体积光与胶片级调色，严禁 2D/3D 卡通感。 | [Visual Style Preset — Cinematic Live-Action Film (cinematic_realistic)]: Photorealistic live-action cinema shot on ARRI Alexa 35mm anamorphic lens, authentic human skin pores and fabric micro-textures, natural physical lighting with volumetric depth, rich theatrical color grading, shallow depth of field, zero 2D cartoon, zero 3D CGI plastic look. | ⏳ 等待异步加载… ⏱ 30.0s · 19.2 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "2d_anime" | 2D 日漫 / 国漫赛璐璐（2D Cel-Shaded Anime） 清晰黑线勾勒、扁平赛璐璐色块与戏剧化冷暖边缘光，严禁 3D 建模感与真人写实。 | [Visual Style Preset — 2D Cel-Shaded Anime (2d_anime)]: Strict 2D hand-drawn cel-shaded Japanese/Chinese anime animation, crisp bold black ink outlines, flat vibrant cel shading, expressive anime eyes and dynamic linework, dramatic rim lighting, zero 3D CGI rendering, zero photorealism. | ⏳ 等待异步加载… ⏱ 30.0s · 23.8 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "3d_xianxia" | 高清 3D 国漫修仙 / 玄幻 CG（3D Xianxia CG） 虚幻引擎 5 电影级 3D 国漫渲染、丝绸流光服饰、粒子法术特效与东方仙侠美学。 | [Visual Style Preset — High-End 3D Xianxia CG Animation (3d_xianxia)]: Unreal Engine 5 cinematic 3D Chinese fantasy animation, exquisite sculpted facial features, flowing silk robes with intricate gold embroidery, luminous spiritual aura particles, volumetric mist and dramatic god-rays, zero flat 2D sketch, zero low-poly. | ⏳ 等待异步加载… ⏱ 30.0s · 23.3 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "american_comic" | 欧美暗黑漫画 / 爽文漫剧（American Graphic Novel） 粗犷美漫墨线、高对比度块面光影、冷硬派奇幻/都市异能漫剧质感。 | [Visual Style Preset — Bold Western Graphic-Novel Animation (american_comic)]: Stylized 2D Western graphic-novel cartoon animation, heavy dynamic ink outlines, high-contrast chiaroscuro shadows, saturated dramatic color palette, kinetic action framing, zero photorealism. | ⏳ 等待异步加载… ⏱ 30.0s · 34.1 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "cyberpunk_neon" | 赛博朋克霓虹科幻（Cyberpunk Neon Sci-Fi） 雨夜全息霓虹反射、高对比青品冷暖色调、近未来机能装甲与潮湿街道高光。 | [Visual Style Preset — Cyberpunk Neon Sci-Fi (cyberpunk_neon)]: High-contrast cyberpunk sci-fi cinema, rain-slicked neon reflections in cyan and magenta, holographic HUD glow, atmospheric mist and lens flares, intricate futuristic tech details. | ⏳ 等待异步加载… ⏱ 30.0s · 22.3 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "ecommerce_ugc" | 电商带货 / 真人种草实拍（E-Commerce UGC） 通透自然日光、高清商品与服装材质细节还原、真实手持/主播种草微距质感。 | [Visual Style Preset — Clean Commercial & UGC Product Showcase (ecommerce_ugc)]: Crisp commercial lifestyle photography and authentic creator UGC look, bright clean natural daylight, true-to-life product material and color fidelity, sharp focus on product and model, zero distortion, no on-screen text. | ⏳ 等待异步加载… ⏱ 30.0s · 9.1 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |

#### 3.2 内置电影学运镜与转场技能库（ skill_preset ）完整提示词与统一剧本 30 秒横向对比样片
针对 AI 视频常见的 跳帧（Jump Frame）、刹车感（Braking Effect）、色调断层与同景别硬切割裂 问题，平台内置了 16 套专业电影学与 GitHub 高星开源导演技能包（全部支持逗号叠加组合，如 "occlusion_wipe,micro_drama_hook,emotion_micro_acting" ） ，每一项均清晰标注 理论/开源仓库出处与开源协议 ，前 10 项提供同剧本 30 秒控制变量对比样片：
| skill_preset 值 | 电影学技能名称与原理说明 | 系统实际注入的完整内置提示词（Built-in Skill Prompt） | 30秒同剧本对比样片（打开后异步逐个加载 · 主备自动容灾 · 永久不清除） |
| "none" | 不注入内置运镜/转场技能（纯原样 / Raw） 不注入任何遮挡转场、切镜或导演技能规则，完全按用户自己的 prompt 执行（长视频仅做基础末帧续接）。 | （空 · 关闭所有内置转场/导演技能规则，100% 按用户原始 prompt 执行） | ⏳ 等待异步加载… ⏱ 30.0s · 18.6 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "occlusion_wipe" | 电影学①·前景遮挡无缝转场（Foreground Occlusion Wipe） 复刻电影学遮挡转场 5 步法：片段 A 末尾用场景内真实前景物（树干/石柱/门框/披风/阴影）沿运镜方向全遮挡镜头，截取低纹理暗部尾帧作为片段 B 首帧，并保持完全同向同速滑出遮挡物，彻底消除跳帧与刹车感。 📌 来源： B站电影学遮挡转场教程 (BV1TkxJ6iEVS) · 经典影视剪辑遮挡法 · Film Theory / Tutorial | [Cinematic Skill — Foreground Occlusion Wipe & Same-Direction Momentum (occlusion_wipe)]: Follow the 5-point Film Occlusion Transition Checklist across segment boundaries: (1) Use a real in-scene foreground object (tree trunk, stone pillar, doorway frame, passing shoulder/cloak, or shadow) as the occluder; (2) In the last 1.5s of Segment k-1, pan/track smoothly in one clear direction until the occluder completely covers the frame (dark, low-texture tail frame); (3) Extract Segment k-1's occluded final frame as Segment k's starting first frame; (4) In Segment k, continue panning/tracking in the EXACT SAME direction and speed (`A进遮挡、B出遮挡方向严格一致，速度接得上` — NEVER reverse camera direction or stop-and-restart) as the occluder wipes off the opposite side to reveal the next space/action. | ⏳ 等待异步加载… ⏱ 30.0s · 17.3 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "cut_on_action" | 电影学②·动接动硬切与30°景别切换（Motivated Cut-on-Action） 经典好莱坞剪辑法则（30-Degree Rule + Cut on Action）：不在同机位同景别硬拼，在动作发力最高点切入 >=30° 机位角度与不同景别（远景->特写->低角度），让观众视线被动作动量带过去。 📌 来源： Hollywood Continuity Editing (Walter Murch) · Rylaispirit/cinematic-video-prompt-skill · MIT | [Cinematic Skill — Motivated Cut-on-Action & >=30° Shot-Scale Switch (cut_on_action)]: Across shot/segment boundaries, NEVER cut between two similar medium shots at the same angle. Cut at the peak of physical movement (turning head, drawing blade, stepping forward) while switching camera angle by >=30° and varying shot scale (Establishing Wide -> Medium Action -> Extreme Close-Up on eyes/hands -> Low-Angle Hero Shot), strictly maintaining the 180-degree axis. | ⏳ 等待异步加载… ⏱ 30.0s · 28.3 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "match_cut" | 电影学③·图形/动作相似性匹配转场（Graphic & Action Match Cut） 今敏 / 库布里克式高级转场：利用前一镜头结尾与下一镜头开头的几何图形相似性（如圆月->眼睛瞳孔、旋转车轮->旋转法阵）或连续挥臂轨迹完成跨时空无缝蒙太奇。 📌 来源： Satoshi Kon / Kubrick Match-Cut Theory · Vincentwei1021/video-shotcraft · Apache-2.0 | [Cinematic Skill — Graphic & Action Match Cut (match_cut)]: Connect shots via a precise visual Match Cut: align the exact geometric shape, screen composition position, and motion trajectory at the end of Shot A (e.g., a circular glowing emblem, a spinning wheel, a rising hand, or an eye close-up) with a matching shape and identical movement vector at the opening of Shot B. | ⏳ 等待异步加载… ⏱ 30.0s · 22.3 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "whip_pan" | 电影学④·极速甩镜动量转场（Kinetic Whip-Pan Transition） 利用镜头高速水平/垂直甩动产生的方向性运动模糊（Motion Blur Streaks）隐藏剪辑点，下一镜以完全相同方向的快速甩入定格接住，适合快节奏反打、突发惊吓或时空闪回。 📌 来源： Kinetic Camera Lexicon · jnMetaCode/ai-shortfilm-prompts · MIT | [Cinematic Skill — Kinetic Whip-Pan Transition (whip_pan)]: Execute a high-energy directional Whip-Pan transition: in the final 0.8s of Shot A, whip the camera rapidly in one direction (e.g. fast whip-pan right `→`) creating natural horizontal motion blur streaks; start Shot B whipping in from the exact same direction (`→`) and decelerating smoothly to lock onto the new subject. | ⏳ 等待异步加载… ⏱ 30.0s · 32.8 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "dolly_zoom_oner" | 电影学⑤·希区柯克变焦与推轨一镜到底（Dolly Zoom & Steadicam Oner） 斯坦尼康长镜头（Oner）配合推轨变焦（Dolly in + Zoom out 空间压缩感），主体在画面中心保持稳定比例而背景透视剧烈纵深变化，极度强化觉醒、震惊或压迫氛围。 📌 来源： Hitchcock Vertigo / Steadicam Oner · wuwangzhang1216/DirectorSKILL · MIT | [Cinematic Skill — Steadicam Long-Take Oner & Vertigo Dolly-Zoom (dolly_zoom_oner)]: Stage an unbroken, fluid Steadicam single-take ('oner') with deliberate Z-axis depth movement: glide forward toward the protagonist while widening perspective (Hitchcock dolly-zoom / perspective compression effect) so the character stays anchored in foreground focus while the background corridor/environment expands dramatically. | ⏳ 等待异步加载… ⏱ 30.0s · 18.2 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "over_shoulder_axis" | 电影学⑥·180度轴线正反打与越肩调度（180° Axis Over-the-Shoulder） 严格遵守电影对话戏 180° 轴线定律（180-Degree Rule）与越肩正反打（OTS）：角色 A 始终在左向右看、角色 B 始终在右向左看，前景虚化对方肩颈建立深邃空间关系，杜绝左右跳轴。 📌 来源： 180-Degree Rule & OTS Staging · eternityspring/shuohao-skills · Apache-2.0 | [Cinematic Skill — 180-Degree Axis & Over-the-Shoulder Shot/Reverse-Shot (over_shoulder_axis)]: Strictly enforce the 180-degree camera axis line across dialogue and confrontation shots: keep Character A consistently on screen-left looking right, and Character B on screen-right looking left. Frame with foreground Over-the-Shoulder (OTS) shallow depth-of-field bokeh to establish spatial depth and eyeline match. | ⏳ 等待异步加载… ⏱ 30.0s · 26.8 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "rack_focus_mood" | 电影学⑦·前景虚实变焦与情绪空镜叙事（Rack Focus & Pillow Shot） 大光圈浅景深焦点转移（Rack Focus：焦点从前景道具/雨滴平滑移至后景人物眼神）配合小津安二郎/王家卫式情绪留白，用光影和焦点引导观众注意力。 📌 来源： Ozu Pillow-Shot & Shallow-DOF Lexicon · popopo-99/zy-cinematic-realism · Open Source | [Cinematic Skill — Shallow-DOF Rack Focus & Atmospheric Mood Framing (rack_focus_mood)]: Use anamorphic shallow depth-of-field (`f/1.4` bokeh) with an intentional Rack Focus pull: start with crisp focus on a meaningful foreground detail (raindrops on glass, a trembling teacup, a glowing blade tip) while the background is creamy bokeh, then smoothly pull focus to the character's expressive eyes in the mid-ground. | ⏳ 等待异步加载… ⏱ 30.0s · 18.4 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "action_choreography" | 电影学⑧·高燃动作博弈与攻防节拍（Action Choreography） 适合武侠/修仙/科幻打斗：单镜单完整攻防节拍（闪避->看破->反击->受击定格），明确交代人物前进/后退方向与冲击波反馈，拒绝原地挥空拳。 📌 来源： Combat Choreography Suite · kangarooking/director-skills (action-fight-prompt) · MIT | [Cinematic Skill — Readable Action & Combat Choreography (action_choreography)]: Stage clear, readable combat physics with explicit movement vectors (advancing forward, sliding backward, side-stepping dodge). Each clip executes ONE complete offensive/defensive exchange (attack -> parry/dodge -> counter-impact -> 1.2s recoil/landing hold) with dynamic tracking camera and crisp impact foley. | ⏳ 等待异步加载… ⏱ 30.0s · 29.5 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "manju_director" | 电影学⑨·漫剧全流程导演技能包（Manju Drama Director v2.2） 完整启用 manju_drama_director v2.2 五大铁律：每镜必传角色设定图+彩色导演分镜符锁画风、内置固定音色配音、单镜单完整微动作+1.2s收势留白、电影学遮挡/动接动转场。 📌 来源： HBAI-Ltd/Toonflow-app · shuyu-labs/BigBanana-AI-Director · zenstory-ai/drama-skills · MIT | [Cinematic Skill — Full Manju Drama Director v2.2 (manju_director)]: Apply all 5 Manju Director laws: (1) Pass character reference sheet + full-color director storyboard sheet into every video call; (2) Lock character voices via deterministic `/opt/hatch/bin/tts speak` (unless `mute_voice=true`); (3) One complete micro-action + 1.2s settle beat per clip with `-ss 0.12` head-flash trim; (4) Seamless Foreground Occlusion Wipe (`遮挡转场`) or >=30° Motivated Cut-on-Action across boundaries. | ⏳ 等待异步加载… ⏱ 32.0s · 15.2 MB（1280×720 · 永久保存） ☁️ 优先① Google/主链直达 🎬 备用② 服务器永久直链 |
| "micro_drama_hook" | 开源导演⑩·黄金3秒冲突钩子与付费卡点（Micro-Drama 3s Hook & Cliffhanger） 源自 zenstory-ai/drama-skills 与 lixiaoxiao9888-create/manju-laoli-skill：0–3秒直接以高反差视觉冲突/反转动作开场（严禁慢节奏空镜铺垫），中段层层递进情绪施压，结尾定格于悬念高潮瞬间。 📦 开源出处： zenstory-ai/drama-skills · lixiaoxiao9888-create/manju-laoli-skill · MIT | [Open-Source Director Skill — Micro-Drama 3-Second Hook & Cliffhanger Rhythm (source: github.com/zenstory-ai/drama-skills, MIT)]: Open immediately at 0.0–3.0s with a high-contrast visual hook or decisive status reversal (NEVER waste the first 3 seconds on static establishing scenery). Escalate interpersonal tension through crisp reaction close-ups in the middle beat, and land the final 1.5s on a dramatic reveal or suspenseful cliffhanger freeze-beat. | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "micro_drama_hook,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |
| "emotion_micro_acting" | 开源导演⑪·潜台词微表情与呼吸落点表演（Subtext Micro-Performance） 源自 kangarooking/director-skills (emotion-performance-director)：拒绝写抽象情绪词（如“她很生气”），按「潜台词→眼神/呼吸/下颌/手指微动作时间序→1秒余韵落点（afterbeat）」驱动真人级细腻表演。 📦 开源出处： kangarooking/director-skills (emotion-performance-director) · MIT | [Open-Source Director Skill — Observable Subtext Micro-Performance (source: github.com/kangarooking/director-skills, MIT)]: Translate abstract emotion into temporally ordered, physically observable behavior (Subtext -> Gaze/Breath/Face/Hand micro-signals -> Afterbeat): depict subtle pupil shift, held breath, jaw tightening, or fingers gripping fabric in sequence rather than generic exaggerated grimacing, ending with a quiet 1.0s emotional afterbeat. | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "emotion_micro_acting,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |
| "xianxia_speed_ramp" | 开源导演⑫·东方仙侠变速运镜与灵力因果链（Xianxia Speed-Ramp & VFX Causality） 源自 liyue-aigc/xianxia-cinematic-video-director 与 seedance-2-5-fight-director：拒绝全程匀速慢推，按「蓄力静帧→极速突进（Speed-Ramp）→法术碰撞环境物理反馈（气浪掀衣/碎石/水面波纹）→收势稳停」编排。 📦 开源出处： liyue-aigc/xianxia-cinematic-video-director · seedance-2-5-fight-director · Open Source | [Open-Source Director Skill — Eastern Xianxia Speed-Ramp & VFX Causality (source: github.com/liyue-aigc/xianxia-cinematic-video-director)]: Avoid monotonous constant-speed camera pushes; choreograph adaptive speed-ramping (stillness -> sudden burst acceleration -> crisp impact hold -> smooth settle) and strict VFX physical causality (energy origin -> projectile trajectory -> shockwave rippling robes, dust, rain, and floor reflections -> clean dissipation). | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "xianxia_speed_ramp,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |
| "tvc_product_hero" | 开源导演⑬·商业TVC产品因果与微距流体质感（Commercial TVC Product Hero） 源自 nutllwhy/seedance-tvc-director 与 Vincentwei1021/video-shotcraft：0–3秒痛点/高光钩子，产品必须参与真实物理交互受力链（开盖/滴落/涂抹/反光），严禁结尾生硬贴片。 📦 开源出处： nutllwhy/seedance-tvc-director · Vincentwei1021/video-shotcraft · MIT / Apache-2.0 | [Open-Source Director Skill — Commercial TVC Hero Shot & Physical Force Chain (source: github.com/nutllwhy/seedance-tvc-director, MIT)]: Direct a high-conversion commercial TVC sequence: capture attention in 0–3s, integrate the product into a physically believable tactile force chain (uncapping, pouring, droplet surface tension, fabric drape, specular rim-light sweep) with stable packaging geometry and crisp macro depth-of-field. | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "tvc_product_hero,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |
| "auteur_wong_kar_wai" | 开源导演⑭·王家卫式抽帧霓虹与前景框景美学（Wong Kar-wai Step-Printing & Frame-in-Frame） 源自 wuwangzhang1216/DirectorSKILL 与 lemomo-ai/lemo-opuscar：利用门框/百叶窗/玻璃反光做前景画中画构图（Frame-within-a-Frame），暖黄钨丝灯撞冷青阴影，营造克制暧昧的电影疏离感。 📦 开源出处： wuwangzhang1216/DirectorSKILL · lemomo-ai/lemo-opuscar · MIT | [Open-Source Director Skill — Auteur Frame-within-a-Frame & Neon Melancholy (source: github.com/wuwangzhang1216/DirectorSKILL, MIT)]: Compose through architectural foreground frames (doorframes, window blinds, mirrors, passing silhouettes) with rich tungsten-amber and emerald-cyan color contrast, lingering handheld intimacy, expressive step-printed motion trails, and unspoken emotional tension. | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "auteur_wong_kar_wai,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |
| "spatial_blocking_continuity" | 开源导演⑮·三维空间走位锁与左右手/道具连戏（Spatial Blocking & Prop Continuity） 源自 eternityspring/shuohao-skills (novel-staging) 与 popopo-99/zy-cinematic-realism：跨镜头锁死环境建筑方位、主光源方向、人物持握道具的左右手与伤痕服饰状态，杜绝穿帮。 📦 开源出处： eternityspring/shuohao-skills · popopo-99/zy-cinematic-realism · Apache-2.0 | [Open-Source Director Skill — Strict 3D Spatial Blocking & Prop/Handedness Lock (source: github.com/eternityspring/shuohao-skills, Apache-2.0)]: Anchor a consistent 3D stage floorplan across all shots: strictly lock key-light direction, architectural landmarks, character left/right handedness when holding weapons or props, garment state, and eye-level horizon so spatial geography never flips between cuts. | 🔗 开源蒸馏直连预设 可单独调用或与任意运镜叠加（如 "spatial_blocking_continuity,occlusion_wipe" ） ⭐ 查看原开源仓库 🎬 参考关联样片 |

#### 3.3 全球开源 AI 影视 / 短剧 / 漫剧导演 Skills 地址库与来源标注（24 大精选仓库）
为方便开发者直接复用社区最成熟的导演分镜、剧本改编、动作武指与商业 TVC 方法论，平台持续搜集整理了 GitHub 上主流的 24 个开源 AI 视频导演 Skills 与制片工作流仓库 （均标注 GitHub 仓库原址、Star 量级与开源许可证；可通过 GET /v1/videos/presets 的 open_source_director_repositories 字段程序化读取）。您可以直接将其中的 SKILL.md 规则传入本接口的 custom_skill 参数或挂载至 muse-director 的 documents 字段使用：
| # | 方向分类 | GitHub 开源仓库地址（标注来源） | Star / 协议 | 核心导演技法与适用场景 |
| 1 | 综合AI视频智能体与镜头工程 | calesthio/OpenMontage ↗ https://github.com/calesthio/OpenMontage | ⭐ 75.8k+ AGPL-3.0 | 全球首个开源多智能体视频生产系统，内置 12 条制片管线与 700+ Agent Skill 影视制作知识文件。 |
| 2 | 综合AI视频智能体与镜头工程 | HBAI-Ltd/Toonflow-app ↗ https://github.com/HBAI-Ltd/Toonflow-app | ⭐ 20.3k+ MIT | 开源 AI 短剧与漫剧工作台，涵盖小说改编方法、角色与场景四视图资产锚定、无限画布与智能分镜。 |
| 3 | 综合AI视频智能体与镜头工程 | chatfire-AI/huobao-drama ↗ https://github.com/chatfire-AI/huobao-drama | ⭐ 16.9k+ Open Source | 火宝短剧一站式 AI 短剧全自动生成平台，覆盖剧本拆解、角色定妆、分镜绘制到成片合成。 |
| 4 | 综合AI视频智能体与镜头工程 | Vincentwei1021/video-shotcraft ↗ https://github.com/Vincentwei1021/video-shotcraft | ⭐ 16.4k+ Apache-2.0 | 面向 Claude Code & Codex 的电影感镜头配方库：124 张镜头配方卡（Shot Recipe Cards）、150 种运镜预览与节拍同步。 |
| 5 | 综合AI视频智能体与镜头工程 | waooAI/waoowaoo ↗ https://github.com/waooAI/waoowaoo | ⭐ 14.7k+ Open Source | 好莱坞标准工业级 AI 影视生产 Agent 平台，支持可控多镜角色资产与画布式分镜导演流。 |
| 6 | 综合AI视频智能体与镜头工程 | HKUDS/ViMax ↗ https://github.com/HKUDS/ViMax | ⭐ 12.8k+ MIT | 港大开源全能多智能体视频生成框架（导演 Director + 编剧 Screenwriter + 制片 Producer 协同调度）。 |
| 7 | 电影风格与大师镜头库 | lemomo-ai/lemo-opuscar ↗ https://github.com/lemomo-ai/lemo-opuscar | ⭐ 11.6k+ MIT | 66 套即用型电影视觉风格提示词与样片工程库，支持按风格母题一键套用与自定义扩展。 |
| 8 | AI短剧与漫剧专项导演 Skills | Forget-C/Jellyfish ↗ https://github.com/Forget-C/Jellyfish | ⭐ 7.1k+ Apache-2.0 | 端到端 AI 短剧制片工作空间：结构化分镜、跨镜头角色/服装一致性管理与镜头预备单。 |
| 9 | AI短剧与漫剧专项导演 Skills | eternityspring/shuohao-skills ↗ https://github.com/eternityspring/shuohao-skills | ⭐ 5.9k+ Apache-2.0 | 跨 Agent 通用短剧制作 7 大 Skill 套件：character-refs、novel-art、novel-staging（三维空间调度）、novel-storyboard。 |
| 10 | AI短剧与漫剧专项导演 Skills | dexhunter/seedance2-skill ↗ https://github.com/dexhunter/seedance2-skill | ⭐ 4.4k+ MIT | 多模态视频提示词工程标准库：@图参考语法、运镜词典、短剧/广告/MV 多镜头结构模板。 |
| 11 | AI短剧与漫剧专项导演 Skills | zenstory-ai/drama-skills ↗ https://github.com/zenstory-ai/drama-skills | ⭐ 3.7k+ MIT | 11 个标准 SKILL.md 组成的开源短剧/漫剧全流程：原著拆解、分集钩子、资产设定、storyboard 分镜、视频提示词与审稿质检。 |
| 12 | AI视频剪辑与故事线导演 | FireRedTeam/FireRed-OpenStoryline ↗ https://github.com/FireRedTeam/FireRed-OpenStoryline | ⭐ 3.6k+ Apache-2.0 | 意图驱动的 AI 导演剪辑 Agent，把自然语言导演意图转化为故事线节拍与镜头组接。 |
| 13 | AI短剧与漫剧专项导演 Skills | lixiaoxiao9888-create/manju-laoli-skill ↗ https://github.com/lixiaoxiao9888-create/manju-laoli-skill | ⭐ 1.8k+ MIT | 漫剧老李 AIGC 全流程导演套装（1 总控 + 12 子技能 + 50 份规则库）：六道前置锁、画风锁、三大打戏引擎与 C1~C32 机检。 |
| 14 | 开源导演 Skills 索引导航大全 | UnderleveledBuilder/awesome-short-drama-skills ↗ https://github.com/UnderleveledBuilder/awesome-short-drama-skills | ⭐ 1.7k+ CC0-1.0 | 人工核对并盲测评分的 83 个 AI 短剧/漫剧 SKILL.md 精选索引库 + 16 个开源制片平台汇总。 |
| 15 | AI短剧与漫剧专项导演 Skills | alibaba/lumenx ↗ https://github.com/alibaba/lumenx | ⭐ 1.4k+ MIT | 阿里巴巴开源 LumenX Studio 动态漫/短漫剧一站式平台：剧本分析、角色定制、分镜绘制与视频合成。 |
| 16 | 电影摄影、表演与大师运镜 Skills | popopo-99/zy-cinematic-realism ↗ https://github.com/popopo-99/zy-cinematic-realism | ⭐ 648+ Open Source | 造梦师 Dream Director：物理可信光影、前景遮挡构图与克制电影感实拍提示词体系。 |
| 17 | 电影摄影、表演与大师运镜 Skills | Shanyin-ai/shanyin-director-master ↗ https://github.com/Shanyin-ai/shanyin-director-master | ⭐ 621+ MIT | 山音超级导演大师：导演定调→节奏规划→剧本微调→工业标准九列分镜表拆解，内置数十种类型片导演模板。 |
| 18 | 电影摄影、表演与大师运镜 Skills | jnMetaCode/ai-shortfilm-prompts ↗ https://github.com/jnMetaCode/ai-shortfilm-prompts | ⭐ 513+ MIT | 覆盖 21 种影片类型与 5 阶段叙事结构的跨模型（Sora / Veo / Kling / Seedance / Muse）电影短片提示词库。 |
| 19 | 商业广告 TVC 与打戏/仙侠导演 Skills | nutllwhy/seedance-tvc-director ↗ https://github.com/nutllwhy/seedance-tvc-director | ⭐ 334+ MIT | 商业广告 TVC 导演 Skill：15s/30s 黄金前三秒钩子、产品物理受力证据链、旁白与画面注意力接力及局部返工诊断。 |
| 20 | 电影摄影、表演与大师运镜 Skills | wuwangzhang1216/DirectorSKILL ↗ https://github.com/wuwangzhang1216/DirectorSKILL | ⭐ 311+ MIT | Cinematic Director v2.1：潜台词拆解、导演阐述本、场面调度（Blocking）及 20 位殿堂级导演（斯皮尔伯格/库布里克/王家卫/诺兰/张艺谋等）风格滤镜。 |
| 21 | 商业广告 TVC 与打戏/仙侠导演 Skills | liyue-aigc/xianxia-cinematic-video-director ↗ https://github.com/liyue-aigc/xianxia-cinematic-video-director | ⭐ 276+ Open Source | 东方仙侠运镜导演 + 高燃打斗导演（同作者 seedance-2-5-fight-director）：变速运镜曲线、攻防路线、法术碰撞环境因果反馈与首尾状态锁。 |
| 22 | 电影摄影、表演与大师运镜 Skills | kangarooking/director-skills ↗ https://github.com/kangarooking/director-skills | ⭐ 258+ MIT | 收录 7 个专项 AI 导演 Skill：情绪微表演导演（emotion-performance-director）、动作打戏导演（action-fight-prompt）、电影资产提示词等。 |
| 23 | 电影摄影、表演与大师运镜 Skills | Rylaispirit/cinematic-video-prompt-skill ↗ https://github.com/Rylaispirit/cinematic-video-prompt-skill | ⭐ 173+ MIT | 700+ 电影摄影专业术语词典与公式化组装器（机位角度、推拉摇移、布光、构图、胶片调色）。 |
| 24 | AI短剧与漫剧专项导演 Skills | LuoJiangYong/muse-video-skill ↗ https://github.com/LuoJiangYong/muse-video-skill | ⭐ 52+ MIT | 视频创作虚拟剧组引擎：38 个经典案例技法库 × 六大剧组角色（导演/编剧/摄影/美术/特效/声音）协作与质量门控。 |

#### 3.4 粘性会话断点续作指南、 muse-director 预扣与结算明细及无直链兜底说明

### 四、邀请码自动填写助力（ muse-invite ）
通过 POST /v1/chat/completions 指定 "model": "muse-invite" ，即可将您的 Muse 邀请码（或邀请链接）交由平台未填码新号完成核销助力（每次 ¥0.09 ）：
- 防重复保障 ：每个助力账号终身仅核销一次邀请码并持久化记录，绝不重复使用已填码账号。
- 失败零损耗恢复 ：若因邀请码拼写错误、已过期或 邀请人已达到邀请上限 导致核销失败，系统自动恢复助力账号状态并返回 HTTP 400 明细原因， 本次调用不扣费 。

### 五、语音合成（ muse-tts ）、语音识别（ muse-asr ）与实时语音（ muse-live ）
| 音色别名 ( voice ) | 原生音色 ID | 音色特征 | 支持输出格式 ( response_format ) |
| alloy / aria / coral | avocado_v2:MAI_01 | Aria · 清亮自然女声 | mp3 （默认）、 wav 、 opus 、 pcm |
| nova / shimmer / sage | avocado_v2:MAI_02 | Nova · 温暖亲和女声 | mp3 、 wav 、 opus 、 pcm |
| echo / helio / onyx | avocado_v2:MAI_03 | Helio · 沉稳磁性男声 | mp3 、 wav 、 opus 、 pcm |
| fable | avocado_v2:bud | Bud · 叙事表现力男声 | mp3 、 wav 、 opus 、 pcm |

### 六、云端沙盒会话粘性（默认关闭 · HMAC 防越权签名令牌）
平台 默认关闭会话粘性 ：未传粘性参数时，每次请求均在全量算力池中随机低负载均衡调度并开启全新对话。一次完整的粘性会话由 「实例混淆摘要 + 会话 ID + HMAC-SHA256 签名（ mconv_<acc_tag>_<conv_id>_<sig> ）」共同唯一确定 ——对外彻底隐藏内部实例 ID，且任何伪造或篡改均会被签名校验拦截（HTTP 400），严防跨实例/跨会话越权：
| 传参位置 | 显式参数 / Header 名 | 示例值 | 行为说明 |
| JSON Body / Header | conversation_id / X-Conversation-Id | "mconv_8a4f19c2e0b73d61_ec11bed9-..._f39c01a8..." | 推荐标准写法 ：首轮对话响应头 X-Conversation-Id 与响应体 conversation_id 会返回带 HMAC-SHA256 签名的 mconv_... 复合令牌，后续轮次原样回传即可安全续接同一实例下的同一会话线程 |
| HTTP Header / Body | X-Session-Id / session_id | "proj_alpha_conv01" | 传入自定义会话 ID 时，系统自动按调用方 API Key 命名空间隔离（不同用户的同名 session_id 互不碰撞）并绑定专属二元组（常规 user 字段不触发粘性） |

### 七、完整调用示例
```
# 1a. 标准云端对话 (muse-chat · 问答/识图/写代码，不主动调用生图生视频工具)
curl -sS https://newapi-2.oairegbox.cc/v1/chat/completions   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -H "X-Session-Id: sess_demo_001"   -d '{
    "model": "muse-chat",
    "messages": [{"role": "user", "content": "你好！请帮我用 Python 写一段快速排序并验证输出。"}],
    "stream": true
  }'

# 1b. 云端自主全能智能体 (muse-agent · 完整开放 Linux 沙盒 + 自动审批 + 可在对话中直接生图/生视频/剪辑并上传直链)
curl -sS https://newapi-2.oairegbox.cc/v1/chat/completions   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -H "X-Session-Id: agent_proj_001"   -d '{
    "model": "muse-agent",
    "messages": [{"role": "user", "content": "请先生成一张赛博朋克女武神的设定图，再以该图作为首帧生成一段 10 秒 16:9 动作视频，最后把图片和视频的 https://muse.ai/files/... 链接发给我。"}],
    "stream": true
  }'

# 1c. 标准 OpenAI 工具调用 (Function Calling · tools / tool_choice) + 深度推理档位 (reasoning_effort)
curl -sS https://newapi-2.oairegbox.cc/v1/chat/completions   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-chat",
    "reasoning_effort": "xhigh",
    "messages": [{"role": "user", "content": "查询东京现在的天气"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的实时天气",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string", "description": "城市名称"}},
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

# 2. 原生 2K 级图像生成（画幅比例 + 风格 + 负向提示词）
curl -sS https://newapi-2.oairegbox.cc/v1/images/generations   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-image",
    "prompt": "赛博朋克雨夜霓虹街道，电影级光影，主角回眸特写",
    "aspect_ratio": "16:9",
    "style": "cinematic",
    "negative_prompt": "blurry, watermark, low quality"
  }'

# 3. 异步生成原生 720p HD 视频（支持 mute_voice 控制人物是否静音，默认 false 发音）
curl -sS https://newapi-2.oairegbox.cc/v1/videos   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-video",
    "prompt": "金色夕阳下的海浪拍打礁石，白衣剑客站在礁石上拔剑凝视远方，镜头缓慢推进",
    "aspect_ratio": "16:9",
    "seconds": "8",
    "camera_motion": "zoom_in",
    "mute_voice": false
  }'

# 3b. 自由组合电影学技能与画风预设（支持内置预设 / 传 "none" 原样直出 / 传 custom_style & custom_skill 自定义）
curl -sS https://newapi-2.oairegbox.cc/v1/videos   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-video-20s",
    "prompt": "Part 1 (0-10s): 男女主在室外柳树花园向右漫步，镜头向右平移，前景粗大树干从右侧扫过全遮挡镜头。Part 2 (10-20s): 镜头保持同向同速向右平移滑出树干，无缝露出金碧辉煌的室内宴会厅。",
    "aspect_ratio": "16:9",
    "seconds": "20",
    "style_preset": "cinematic_realistic",
    "skill_preset": "occlusion_wipe,over_shoulder_axis",
    "custom_style": "Warm golden-hour rim lighting, Kodak Vision3 500T film grain",
    "custom_skill": "Keep camera panning speed strictly constant at 1.0x across the 10s occlusion boundary",
    "mute_voice": true
  }'

# 3c. AI 漫剧/短剧导演模型 (muse-director · 自动按剧情节拍切分镜头 + 角色设定图锁画风 + 按实际生图张数与视频秒数计费)
curl -sS https://newapi-2.oairegbox.cc/v1/videos   -H "Authorization: Bearer <YOUR_API_KEY>"   -F "model=muse-director"   -F "aspect_ratio=16:9"   -F "seconds=30"   -F "mute_voice=false"   -F "prompt=2D cel-shaded anime fantasy drama: Episode 1, natural beat cuts, switch camera angle on every clip boundary"   -F "script_file=@./episode1_script.md"   -F "image=@./hero_character_sheet.png"

# 3d. 失败/中断的长视频或导演任务断点续作（传入原会话 session_id 或调用 /v1/videos/{task_id}/remix，直接复用已生成的分段补齐剩余部分）
curl -sS https://newapi-2.oairegbox.cc/v1/videos   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-video-60s",
    "session_id": "77c47db2-59fa-4228-a9a0-ce1612c595f2",
    "prompt": "继续生成缺失的最后一段（Part 6），并将 workspace 下全部 6 段合成完整 60 秒视频上传"
  }'

# 4. 邀请码自动填写助力 (muse-invite · ¥0.09/次)
curl -sS https://newapi-2.oairegbox.cc/v1/chat/completions   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-invite",
    "messages": [{"role": "user", "content": "1X3KVY"}]
  }'

# 5. Avocado v2 语音合成 (muse-tts)
curl -sS https://newapi-2.oairegbox.cc/v1/audio/speech   -H "Authorization: Bearer <YOUR_API_KEY>"   -H "Content-Type: application/json"   -d '{
    "model": "muse-tts",
    "voice": "alloy",
    "input": "欢迎体验 Meta Muse 全模态极速语音合成服务。",
    "response_format": "mp3"
  }' -o muse_speech.mp3

# 6. 极速语音识别转写 (muse-asr)
curl -sS https://newapi-2.oairegbox.cc/v1/audio/transcriptions   -H "Authorization: Bearer <YOUR_API_KEY>"   -F "model=muse-asr"   -F "file=@muse_speech.mp3"
```