# AruHub 视频模型接入说明

核对日期：2026-10-31。使用你自己的 AruHub 密钥。以下为三篇教程的完整文本。


# 视频 API 接入与 AI 配置

本页是 [Seedance 2.5](https://docs.aruhub.com/guide/seedance-2-5) 和 [Grok 视频](https://docs.aruhub.com/guide/grok-video) 的共用接入说明。接口核对日期：2026-10-31。面向普通用户、开发者和替用户配置的 AI。

**你需要实现的是一个异步任务流程：**

```text
用户输入提示词 / 素材
        ↓
POST /v1/videos（提交一次）
        ↓
保存响应顶层 id → 页面刷新 / 断线后仍可使用
        ↓
GET /v1/videos/{id}（间隔查询）
        ├─ queued / in_progress → 等待后继续 GET
        ├─ failed → 读取 error.message，显示原因并停止
        └─ completed → video_url 或 metadata.url → 下载 / 保存 / 播放
```

生成完成和下载成功是两个步骤。HTTP 200、进度到 100、用量记录出现，都不能单独证明用户已经收到完整视频。

## 接入准备

1. 从 [我的密钥](https://aruhub.com/keys) 获取自己的 AruHub API Key。密钥需具备目标模型权限。
2. 确认工具支持**自定义视频接口和异步任务**。只支持聊天、图片或同步响应的软件，需要新增视频工具或 HTTP 工作流。
3. 确认模型 ID。本文使用 `seedance2.5`、`grok-imagine-video`、`grok-imagine-video-1.5`，以你的密钥当前可用列表为准。
4. 把密钥放在本地环境变量、工具的凭据管理器或网站后端配置中。公开文档、源码和发送给 AI 的提示词只放占位符。

### 不生成视频，先检查密钥和模型

Bash 中设置当前终端环境变量：

```bash
read -r -s -p 'AruHub API Key: ' ARUHUB_API_KEY
echo
export ARUHUB_API_KEY

curl --fail-with-body --max-time 30 \
  https://api.aruhub.com/v1/models \
  -H "Authorization: Bearer $ARUHUB_API_KEY"
```

在返回的 `data` 数组里查找目标模型的 `id`。模型列表能验证密钥访问与模型可见性，但不等于已经验证素材、参数和实际生成。

### 地址填写规则

| 软件要求的字段 | 正确填写 |
| --- | --- |
| HTTP 节点 / cURL 的完整请求 URL | `https://api.aruhub.com/v1/videos` |
| 软件会追加 `/v1/videos` | Base URL 填 `https://api.aruhub.com` |
| 软件会追加 `/videos` | Base URL 填 `https://api.aruhub.com/v1` |
| Studio，协议选 New API | Base URL 填 `https://api.aruhub.com` |
| 请求头 | `Authorization: Bearer 你的密钥`，注意 Bearer 后有空格 |

本文使用 `api.aruhub.com`。不要把主站网页、文档站、Studio 地址或通用 Agent 域名填进视频请求。遇到 404 先检查最终发出的 URL，而不是凭软件字段名称猜测是否需要 `/v1`。

## 两个模型怎么选参数

| 项目 | Seedance 2.5 | Grok 视频 |
| --- | --- | --- |
| 模型 ID | `seedance2.5` | `grok-imagine-video` / `grok-imagine-video-1.5` |
| 最小验证参数 | 4 秒、480p、16:9 | 6 秒、480p、16:9 |
| 时长字段 | `duration`，4～30 秒整数 | `duration`，1～15 秒整数，必须给出 |
| 比例字段 | `ratio` | `aspect_ratio` |
| 初次使用分辨率 | `480p`，后续可用 `720p` | `480p`，后续按目标模型验证 `720p` 等 |
| 图片参考 | `images` 数组，最多 30 张 | `image: {"url":"..."}`，单张 |
| 视频 / 音频参考 | `videos` / `audios` 数组 | 当前接入不支持 |
| 本地文件直接上传 | multipart，或 JSON Data URI | 本教程只推荐单图公网 URL JSON |
| 结果地址 | `video_url`，兼容 `metadata.url` | 当前常在 `metadata.url`，可能为相对 content 路径 |

模型专属限制、素材大小和详细示例分别见两篇模型教程。不要用一份不区分模型的表单把所有字段原样发送给两个模型。

## 两套协议对照

**新开发推荐统一采用第一套 `/v1/videos`。** 如果软件已经使用第二套，就按第二套的查询结构解析。

| 项目 | 推荐：Videos 兼容接口 | New API 通用任务接口 |
| --- | --- | --- |
| 创建 | `POST /v1/videos` | `POST /v1/video/generations` |
| 查询 | `GET /v1/videos/{task_id}` | `GET /v1/video/generations/{task_id}` |
| 本文两个模型的创建 ID | 顶层 `id`；当前也有 `task_id` | 当前适配器创建响应同样返回顶层 `id` / `task_id`；不要因为查询有包装就假设创建也有包装 |
| 查询任务对象 | 顶层 JSON | 顶层 `code: "success"` 后的 `data` |
| 查询状态 | 顶层 `status` | `data.status` |
| 等待中 | `queued` / `in_progress` | `NOT_START` / `SUBMITTED` / `QUEUED` / `IN_PROGRESS` 等非终态 |
| 完成 | `completed` | `SUCCESS` |
| 失败 | `failed` + `error.message` | `FAILURE` + `data.fail_reason` |
| 视频地址 | `video_url` 或 `metadata.url` | `data.result_url` |

第二套完成响应的简化示意：

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "YOUR_LOCAL_TASK_ID",
    "status": "SUCCESS",
    "result_url": "/v1/videos/YOUR_LOCAL_TASK_ID/content",
    "fail_reason": ""
  }
}
```

不能把 `code: "success"` 当成“视频生成成功”：它表示该查询请求成功，视频是否完成要看 `data.status`。包装对象内的数字数据库 `data.id`、更深层供应商 `data.data.id` 或 `request_id` 不是新客户端应保存的创建任务 ID。

`/v1/videos/generations`（videos 为复数）是另一种原生协议的路径，不是上面这两套 AruHub 创建路径。不要混淆三个相似地址。

## Windows PowerShell

使用 PowerShell 原生 HTTP 命令可避免 Bash 的反斜杠续行和 JSON 引号问题。下面通过隐藏输入获取密钥，仅保存在当前终端环境：

```powershell
$secureKey = Read-Host 'AruHub API Key' -AsSecureString
$env:ARUHUB_API_KEY = [System.Net.NetworkCredential]::new('', $secureKey).Password
$headers = @{ Authorization = "Bearer $env:ARUHUB_API_KEY" }

# 只查看可用模型，不创建视频
$models = Invoke-RestMethod -Uri 'https://api.aruhub.com/v1/models' -Headers $headers
$models.data | Where-Object { $_.id -match 'seedance|grok-imagine-video' } | Select-Object id
```

准备好后，以下代码**会创建一次视频任务**：

```powershell
$payload = @{
  model = 'seedance2.5'
  prompt = '一只橘猫坐在窗边，镜头缓慢推进，自然光。'
  duration = 4
  resolution = '480p'
  ratio = '16:9'
}
$json = $payload | ConvertTo-Json -Depth 10
$created = Invoke-RestMethod -Method Post -Uri 'https://api.aruhub.com/v1/videos' `
  -Headers $headers -ContentType 'application/json' `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($json)) -TimeoutSec 180
if (-not $created.id) { throw '创建响应缺少 id，请保留响应检查，不要自动重新提交。' }
$created.id | Set-Content -LiteralPath '.\aruhub-task-id.txt' -Encoding utf8
$created | ConvertTo-Json -Depth 10
```

Grok 用户将 payload 改为：

```powershell
$payload = @{
  model = 'grok-imagine-video'
  prompt = 'A red ball on a wooden table, gentle daylight, static camera.'
  duration = 6
  resolution = '480p'
  aspect_ratio = '16:9'
}
```

然后使用同样的创建代码。**不要先创建 Seedance，再误把 Grok 的 payload 当成查询命令执行。**

查询已经保存的任务，不会创建新视频：

```powershell
$taskId = (Get-Content -Raw -LiteralPath '.\aruhub-task-id.txt').Trim()
$status = Invoke-RestMethod -Uri "https://api.aruhub.com/v1/videos/$taskId" -Headers $headers
$status | ConvertTo-Json -Depth 10
```

完整自动轮询与下载建议直接使用下方可运行脚本。若使用 cURL，PowerShell 中请明确调用 `curl.exe`，不要直接复制 Bash 中的 `\` 换行语法。

## 可运行脚本与断线续查

提供两个完整示例，均使用 `/v1/videos`：

- [下载 Python 脚本](https://docs.aruhub.com/downloads/aruhub_video.py)：Python 3.10+，只使用标准库，无需安装 SDK。
- [下载 Node.js 脚本](https://docs.aruhub.com/downloads/aruhub-video.mjs)：Node.js 20+，使用内置 fetch，无需安装 SDK。
- [下载 Seedance 示例请求](https://docs.aruhub.com/downloads/seedance-request.json)。
- [下载 Grok 示例请求](https://docs.aruhub.com/downloads/grok-request.json)。

脚本行为：读取 `ARUHUB_API_KEY`，创建一次并保存任务 ID；轮询完成后下载；GET 临时故障退避重试；POST 超时或响应不确定时不自动重新提交；相对结果地址解析到 API 域名；只向本站发送 AruHub 密钥。

### Python 使用方式

将脚本和 JSON 保存到同一个文件夹，在该文件夹打开终端。先设置前文的 `ARUHUB_API_KEY` 环境变量。

```bash
# 第一次调用：会创建一个视频任务
python aruhub_video.py create seedance-request.json seedance-task.json seedance-result.mp4

# Grok：另选此命令，不需要把两条都执行
python aruhub_video.py create grok-request.json grok-task.json grok-result.mp4

# 网络中断、等待超时或重启后：继续已有任务，不重新创建
python aruhub_video.py resume seedance-task.json seedance-result.mp4
```

Windows 如使用 Python Launcher，可把 `python` 换成 `py -3`。

### Node.js 使用方式

```bash
node aruhub-video.mjs create seedance-request.json seedance-task.json seedance-result.mp4
node aruhub-video.mjs resume seedance-task.json seedance-result.mp4
```

Grok 将请求文件、任务文件和输出文件替换为对应名称即可。不要把两种脚本同时用于创建同一个业务请求。

### 保存文件的含义

| 文件 | 用途 |
| --- | --- |
| `*-request.json` | 你希望生成的参数，可以编辑提示词；不是响应 |
| `*-task.json` | 保存创建返回的本地任务 ID、模型及提交状态；不要删除后重新创建来解决下载问题 |
| `*-result.mp4.part` | 下载中的临时文件，尚未确认完整 |
| `*-result.mp4` | 完整下载通过检查后的成片 |

示例脚本为了避免误重复提交，在创建前会保留任务文件。如果 POST 超时且没有拿到 ID，文件会标记为“创建结果不确定”；此时检查控制台记录或联系支持，确认原请求结果后再决定下一步。**文件存在时脚本不会自动发起另一次创建。**

脚本默认最多等待 30 分钟，这是客户端示例的等待上限，不是服务完成时限或任务取消时间。超时后任务可能仍在运行，保留文件并用 `resume` 继续。关闭终端、关闭网页或停止轮询都不等于取消服务器任务。

### 请求文件内容

Seedance：

```json
{
  "model": "seedance2.5",
  "prompt": "一只橘猫坐在窗边，镜头缓慢推进，午后自然光，动作平稳。",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9"
}
```

Grok：

```json
{
  "model": "grok-imagine-video",
  "prompt": "A small red ball on a wooden table, gentle daylight, static camera.",
  "duration": 6,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}
```

脚本支持在请求 JSON 中增加各模型支持的素材字段。Seedance multipart 的 cURL 示例见 [Seedance 教程](https://docs.aruhub.com/guide/seedance-2-5)；本脚本使用 JSON，不自动转换本地文件路径。

## 工作流工具怎么连

不依赖某个工具版本的按钮名称，使用 HTTP 请求、等待和条件判断节点即可。n8n、Dify、Coze 或其他平台是否支持长时间任务、循环和持久化，需要按你实际使用的运行环境确认。

| 步骤 | 节点配置 | 输出 / 下一步 |
| --- | --- | --- |
| 1. 用户输入 | 模型、提示词、时长、素材等；API Key 放凭据管理器 | 组装模型专属 JSON |
| 2. 创建 | POST 完整地址 `https://api.aruhub.com/v1/videos`；Bearer 鉴权；JSON body；关闭自动重试 | 提取顶层 `id` |
| 3. 持久化 | 把 `id`、用户 / 业务记录 ID、模型、创建时间保存到数据库或持久变量 | 不只放在当前节点的临时输出里 |
| 4. 等待 | 首次约 5 秒，后续可退避 | 进入查询节点 |
| 5. 查询 | GET `https://api.aruhub.com/v1/videos/` + 保存的 `id`；同一密钥 | 判断 `status` |
| 6. 分支 | queued/in_progress 回到等待；failed 记录错误；completed 读取结果 | 不回到创建节点 |
| 7. 下载 | 提取 `video_url` 或 `metadata.url`；相对路径补 API 域名；本站地址带密钥，外部地址不带 | 响应按二进制文件处理 |
| 8. 交付 | 保存对象存储地址 / 文件，通知你自己的前端 | 可以显示预览和下载按钮 |

整个流程的执行时间要覆盖排队和生成。若工作流平台单次运行上限较短，把创建与定时查询拆开：创建后保存 ID，由后续定时任务继续查询。不要通过“循环重跑整个工作流”模拟轮询，否则会重复创建视频。

模型输出 URL 不能直接假设是永久 URL。若工作流最终只返回临时地址，用户稍后打开可能失效；长期使用应及时保存成片。

## 自建网站与 AI Agent

网站后端应分别提供“创建任务”“查询任务”“获取成片”的业务接口。业务数据库保存本站任务 ID 与自己用户的归属；前端拿你自己的业务 ID，后端再映射到 AruHub ID。仅检查一个字符串 ID 存在不等于做了用户权限校验。

让 AI Agent 调用时，建议提供三个明确的工具：

```text
create_video(model, prompt, duration, resolution, ratio_or_aspect, references)
  -> 返回本地任务ID，立即保存。仅在用户要新生成时调用。

get_video_status(task_id)
  -> 返回等待 / 完成 / 失败，以及结果地址或错误。

download_video(task_id, result_url)
  -> 按域名处理鉴权，保存到明确的文件路径或对象存储。
```

在 Agent 的工具说明里明确：**轮询或下载失败不能自动调用 create_video；先恢复原任务。** 任务状态不确定时应告诉用户“仍在确认”，不能把等待、网络错误或下载失败统一写成“生成失败”。

仅支持 Chat Completions 的 OpenAI 兼容客户端不会因为加了 `seedance2.5` 模型名就自动获得视频能力。通用聊天 SDK 的 `chat.completions.create()` 也不会变成视频接口；没有匹配的视频接口时，直接使用 HTTP 示例最清楚。

## 下载与重试规则

| 场景 | 正确处理 |
| --- | --- |
| 创建成功拿到 `id` | 保存，然后只查这个 ID |
| POST 超时、连接断开、5xx、响应丢失 | 可能已经受理，先查记录 / 联系支持，不盲目重发 |
| GET 查询网络错误、429、5xx | 延迟后重试原查询；有合理 `Retry-After` 时遵循它 |
| GET 401 / 403 | 检查密钥、权限和任务归属；不要无限重试 |
| GET 404 | 检查域名、端点、任务 ID 和身份；不要换用供应商 ID |
| status 为 failed | 保存错误并停止；是否新建由用户决定 |
| completed 但没有任何结果地址 | 保留原始响应和任务 ID 排查，不自动重新生成 |
| completed 但下载网络失败 | 重新查询获得结果地址，重试下载原视频 |
| 视频响应 206 | 检查 Content-Range，确认是否完整或需要分段续传 |
| 相对地址 | 使用 `https://api.aruhub.com` 作为 URL 解析基准 |
| 外部结果域名或重定向 | 不发送本站 Authorization 头 |

不要依赖 `Idempotency-Key`、`client_request_id` 或 `request_id` 自动去重：本文没有承诺创建接口提供幂等重试保证。客户端应自行保存业务提交状态、禁用重复点击并避免自动重发。

不要只按文件扩展名判断下载成功。核对响应状态、Content-Type、实际字节数和媒体内容；HTML 错误页或 JSON 报错即使被保存成 `.mp4` 也不能播放。

## 通用报错排查

| 状态 / 现象 | 优先检查 |
| --- | --- |
| 400 / 422 | 查看响应中的错误信息；检查模型字段、类型、时长、素材、冲突参数 |
| 401 | 密钥是否完整、Bearer 后是否有空格、是否误用其他服务的密钥 |
| 403 | 权限、任务归属、素材访问或内容限制；按具体错误确认 |
| 404 | 最终 URL 是否正确、是否重复 `/v1`、ID 是否为本站创建返回值 |
| 413 | 素材大小、Base64 增量、HTTP 节点 / 反向代理请求体限制 |
| 429 | 减少并发和轮询频率；查询可退避重试，创建需先确认是否受理 |
| 5xx / 网络超时 | 区分创建、查询、下载哪个步骤；分别按上表处理 |
| 有任务但前端没卡片 | 检查创建响应 `id` 提取、任务持久化与前端状态更新 |
| 有地址但播放器打不开 | 检查鉴权、相对 URL 基准、跨域、文件完整性和浏览器媒体支持 |

向支持人员提供：发生时间及所在时区、模型 ID、最终接口路径、HTTP 状态码、任务 ID（仅提供给可信支持渠道）、脱敏错误响应、是否为创建 / 轮询 / 下载、是否已经得到过 `completed`。不要提供完整 API Key、Authorization 头、Base64 素材或带授权信息的媒体链接到公开群聊。

## 交给 AI 的完整任务模板

```text
请帮我接入 AruHub 视频 API。先阅读：
https://docs.aruhub.com/guide/video-api
Seedance：https://docs.aruhub.com/guide/seedance-2-5
Grok：https://docs.aruhub.com/guide/grok-video
纯文本说明：https://docs.aruhub.com/downloads/aruhub-video-ai-guide.md

我的环境：填写 Windows/macOS/Linux，以及软件名或项目语言。
我的目标：填写 Seedance 2.5 或 Grok，以及文生视频/单图/多素材需求。
我的输出位置：填写本地目录或对象存储；不清楚时先用当前目录。
密钥已放在 ARUHUB_API_KEY 环境变量，或由我在软件的凭据设置中填写。
请不要要求我把真实密钥粘贴进聊天；

执行要求：
1. 先检查环境和现有配置，解释将改动的文件或设置。
2. 用 GET https://api.aruhub.com/v1/models 验证目标模型可见，不把这当成已完成生成验收。
3. 新代码使用 POST /v1/videos + GET /v1/videos/{本地id}；避免 /v1/v1 和原生xAI路径。
4. 按目标模型使用正确字段，尤其 Seedance ratio 与 Grok aspect_ratio 的区别。
5. 创建后持久保存顶层id，禁用POST自动重试；查询与下载可以适当退避。
6. 解析 queued/in_progress/completed/failed；结果读取 video_url || metadata.url。
7. 相对地址解析到API根域名；本站content下载带Bearer，外部下载与跨域跳转不带密钥。
8. 保存二进制成片并检查完整性；网页播放通过后端受保护地址或保存后的媒体地址。
9. 支持进程退出后恢复查询同一个任务；不把停止轮询当成取消服务端任务。
10. 软件若没有异步视频能力，明确提出需要增加HTTP工作流/工具，不要只添加模型名就报告成功。
11. 先展示脱敏的最终请求URL、JSON、配置文件位置和运行命令；确认试运行意图后只发一次最小任务。
12. 报告实际验证到哪一步：模型可见、创建受理、任务完成、下载成功、播放成功分别说明。
```

## 接入完成的检查清单

- [ ] 当前密钥能看到目标模型，实际请求域名与路径正确。
- [ ] 参数符合目标模型限制，素材是直链或该模型支持的上传形式。
- [ ] 创建只提交一次，并立即保存返回的本站 `id`。
- [ ] 刷新页面 / 重启进程后可继续查询同一个任务。
- [ ] 等待、失败、完成三种分支都能正确处理，错误信息可读。
- [ ] 兼容 `metadata.url` 与相对路径；未把密钥传给外部媒体域名。
- [ ] 成片已完整保存；如提供网页播放，还实际检查播放和进度拖动。

[Seedance 2.5 视频](https://docs.aruhub.com/guide/seedance-2-5) · [Grok 视频](https://docs.aruhub.com/guide/grok-video) · [下载 AI 可读说明](https://docs.aruhub.com/downloads/aruhub-video-ai-guide.md)


---


# Seedance 2.5 视频

使用 AruHub 的 `seedance2.5` 模型生成视频。本文按 AruHub 当前接入方式编写，适合第一次配置的用户、开发者，以及代用户配置软件的 AI。接口核对日期：2026-10-31。

**最短流程：准备密钥 → 提交生成请求 → 保存任务 ID → 查询至完成 → 获取并保存视频。** 创建请求返回的是任务，通常不会立即返回成片。

## 先选适合你的接入方式

| 你的情况 | 怎么做 |
| --- | --- |
| 不写代码，想在网页中生成 | 使用 [AruHub Studio](https://studio.aruhub.com)，按下面的 Studio 配置操作 |
| 已有支持异步视频 API 的软件 | 配置 API 地址、密钥、模型和视频协议；必须支持查询任务和读取结果 |
| 使用 n8n、Dify、Coze 或自建工作流 | 使用 HTTP 请求节点，按 [视频 API 接入与 AI 配置](https://docs.aruhub.com/guide/video-api) 连接提交、轮询和下载 |
| 让 AI 修改网站或写脚本 | 把本页末尾的“交给 AI 的配置指令”和 [共用接入文档](https://docs.aruhub.com/guide/video-api) 一起发给 AI |
| 只有聊天窗口或图片生成节点 | 需要额外接入视频工具；仅在聊天模型列表中填模型名不能完成视频工作流 |

## 1. 准备地址、密钥和模型

| 项目 | 填写内容 |
| --- | --- |
| API 域名 | `https://api.aruhub.com` |
| SDK / 通用兼容客户端的 Base URL | `https://api.aruhub.com/v1`，前提是软件只自动追加 `/videos` |
| 完整创建地址 | `https://api.aruhub.com/v1/videos` |
| 完整查询地址 | `https://api.aruhub.com/v1/videos/{task_id}` |
| API Key | 你自己的 AruHub API 密钥 |
| 模型 ID | `seedance2.5`，注意没有连字符：不是 `seedance-2.5` |
| 鉴权请求头 | `Authorization: Bearer YOUR_API_KEY` |
| 推荐请求格式 | `application/json`；本地文件也可用 `multipart/form-data` |

在 [我的密钥](https://aruhub.com/keys) 创建或取得密钥。密钥必须有目标模型的调用权限。可先请求 `GET https://api.aruhub.com/v1/models`，检查 `data[].id` 中是否有 `seedance2.5`。完整操作见 [接入准备](https://docs.aruhub.com/guide/video-api#接入准备)。

::: tip Base URL 与完整请求地址是两种填写方式
HTTP 请求工具直接填完整地址。会自动拼接 `/v1/videos` 的软件应填根域名；只拼接 `/videos` 的 SDK 应填带 `/v1` 的地址。最终请求必须是 `/v1/videos`，不能出现 `/v1/v1/videos`。文档网站 `docs.aruhub.com` 不是 API 地址。
:::

本文使用统一模型 `seedance2.5`，通过 `resolution` 选择分辨率。不要根据分辨率自行拼接模型后缀；只有密钥实际返回且明确支持的模型 ID 才能使用。

## 2. 在 Studio 中配置

1. 打开 [AruHub Studio](https://studio.aruhub.com)，进入设置中的视频模型配置，新增视频模型。
2. 选择 **New API** 协议。Base URL 填 `https://api.aruhub.com`，API Key 填自己的 AruHub 密钥。
3. 获取模型并选择 `seedance2.5`；若界面允许手动填写，必须使用这个完整 ID。
4. 保存后进入视频生成工作台，选择刚配置的模型。先用 **4 秒、480p、16:9、无参考素材** 验证基本流程。
5. 输入提示词并提交一次，等待任务完成后预览、下载。再逐步添加图片、视频或音频参考。

Studio 的 New API 协议使用 `/v1/video/generations`，由 Studio 处理对应返回格式；下方开发者示例使用 `/v1/videos`。两种入口都可用于本站视频任务，但自建客户端不要混用其状态解析方式。

通用参数面板可能显示其他模型使用的选项。**面板里能选择，不等于当前模型支持。** Seedance 2.5 本教程使用 480p / 720p、4～30 秒以及下表中的比例；不要因为界面显示 4K 或更长时长就直接使用。

## 3. 参数怎么填

| 参数 | 类型 | 必填 / 默认 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 必填 | `seedance2.5` |
| `prompt` | string | 必填 | 非空提示词，最多 20,000 个字符 |
| `duration` | integer | 建议明确填写；默认 15 | 视频秒数，4～30 的整数，例如 `4`、`10`、`15` |
| `resolution` | string | 建议明确填写；默认 `720p` | 本教程使用 `480p` 或 `720p`，带字母 `p` |
| `ratio` | string | 默认 `16:9` | `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9` |
| `mode` | string | 可选；默认 `pro` | 当前接入接受 `pro` / `mini`；首次接入使用 `pro` |
| `images` | string[] | 可选 | 参考图片，最多 30 张 |
| `videos` | string[] | 可选 | 参考视频，最多 10 个 |
| `audios` | string[] | 可选 | 参考音频，最多 10 段 |

分辨率填写 `720p`，比例填写 `16:9`，时长填写整数 `10`，这三项不能互换。当前适配层能识别 `1080p` 字段值，但本文核对的 Seedance 可用配置以 480p / 720p 为准，不把 1080p 作为可直接照抄的选项。

兼容旧客户端时，时长可用 `seconds` 或 `duration_seconds`，比例可用 `aspect_ratio` / `aspectRatio`。**新接入统一使用 `duration`、`resolution`、`ratio`，不要同时发送多套重复参数。** 若重复字段值冲突会被拒绝，例如 `duration: 4` 与 `seconds: "10"`。

`size` 表示像素尺寸，通常不需要填写。如果客户端强制要求，常见对应为 720p 横屏 `1280x720`、竖屏 `720x1280`；480p 横屏 `854x480`、竖屏 `480x854`。`size`、`resolution`、`ratio` 必须相互一致，不要填写 `auto`。

## 4. 文生视频：先跑通最小请求

以下命令在 macOS / Linux 的 Bash 中执行。先设置 `ARUHUB_API_KEY` 环境变量；Windows 用户见 [PowerShell 示例](https://docs.aruhub.com/guide/video-api#windows-powershell)。不要把真实密钥贴到公开代码或发给 AI。

```bash
curl --fail-with-body --max-time 180 \
  https://api.aruhub.com/v1/videos \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "seedance2.5",
    "prompt": "一只橘猫坐在窗边，微风轻轻吹动窗帘。镜头缓慢推进，午后自然光，动作平稳。",
    "duration": 4,
    "resolution": "480p",
    "ratio": "16:9",
    "mode": "pro"
  }'
```

创建响应结构示意如下，实际可能附带其他字段：

```json
{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "seedance2.5",
  "status": "queued"
}
```

马上保存顶层 `id`。`YOUR_LOCAL_TASK_ID` 只是占位符，必须替换为这次创建实际返回的值。HTTP 200 表示创建请求被受理，`queued` 不代表完成；不要再次 POST 来“获取结果”。

## 5. 图生视频：公网图片 URL

在最小请求里加入 `images` 数组。图片地址必须指向实际图片内容，能够由公网服务读取，不能是网页分享页、需要登录的网盘页面或本机文件路径。

```json
{
  "model": "seedance2.5",
  "prompt": "以参考图为主体，保留服装、脸部和背景特征。人物自然抬头，镜头缓慢推近，动作连贯。",
  "duration": 6,
  "resolution": "720p",
  "ratio": "9:16",
  "images": ["https://YOUR_PUBLIC_MEDIA_HOST/reference.jpg"]
}
```

把占位地址替换为你自己的可访问图片直链。多张图片使用同一个数组，保持顺序，并在提示词里说明每张图片的用途，例如“第一张作为人物外观参考，第二张作为场景参考”。这是一种表达意图的方式，不保证模型精确绑定每个编号。

当前链路把图片作为**参考素材**处理。不要把第一张、最后一张图片自动解释成“首帧 / 尾帧”，也不要发送 `first_frame`、`last_frame` 等角色值来强制首尾帧。

## 6. 同时使用图片、视频和音频参考

```json
{
  "model": "seedance2.5",
  "prompt": "参考图片中的产品外观，参考视频中的运镜节奏，并参考音频的节奏设计画面。产品在自然光下缓慢旋转，保持主体一致。",
  "duration": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "images": ["https://YOUR_PUBLIC_MEDIA_HOST/product.png"],
  "videos": ["https://YOUR_PUBLIC_MEDIA_HOST/motion.mp4"],
  "audios": ["https://YOUR_PUBLIC_MEDIA_HOST/rhythm.mp3"]
}
```

这些字段提交参考素材，不是直接拼接素材的剪辑接口。输入音频不等于保证逐字配音、口型同步或原音轨完整保留；输入视频不等于续写、延长或编辑该视频的专用接口。最终参考效果由模型生成结果决定。

### 素材格式与大小

| 素材 | 接受格式 | 数量上限 | 内联 / 文件上传限制 |
| --- | --- | --- | --- |
| 图片 | JPEG/JPG、PNG、WebP、GIF | 30 张 | 单张 20 MiB |
| 视频 | MP4、MOV、WebM | 10 个 | 单个 50 MiB |
| 音频 | MP3、WAV、M4A、AAC、OGG | 10 段 | 单个 50 MiB |

一个请求内全部内联素材解码后的总大小不超过 **50 MiB**；完整请求体上限 **72 MiB**。数量上限和总大小上限需要同时满足，不能据单文件上限推算可上传 30 × 20 MiB。1 MiB = 1,048,576 字节。公网 URL 的实际可用性还取决于素材是否可读取及上游是否接受其编码。

Base64 会增加请求体大小，接近大小上限时优先使用可访问的公网直链。HEIC、AVIF、TIFF、BMP、SVG 请先转成受支持格式；改扩展名并不会转换真实文件格式。文件容器通过检查，也不代表其中的所有编解码器都被模型服务接受。

### 本地文件：multipart 上传

推荐用下面的方法提交电脑上的图片，不需要先自行搭建图片服务器：

```bash
curl --fail-with-body --max-time 180 \
  https://api.aruhub.com/v1/videos \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  -F 'model=seedance2.5' \
  -F 'prompt=让参考图中的主体自然运动，镜头缓慢推进，保持外观一致。' \
  -F 'duration=4' \
  -F 'resolution=480p' \
  -F 'ratio=16:9' \
  -F 'images=@./reference.jpg;type=image/jpeg'
```

多张图片重复 `-F 'images=@...'`；视频使用 `videos=@./reference.mp4;type=video/mp4`；音频使用 `audios=@./reference.mp3;type=audio/mpeg`。Windows 中用 `curl.exe`，并使用实际文件路径。

**multipart 不要手动添加 `Content-Type: application/json`，也不要自己编造 boundary。** 让 cURL、浏览器 FormData 或 HTTP 库自动生成正确的请求头。

### JSON 内联素材：Data URI

没有公网地址、又需要统一使用 JSON 时，可把文件编码为包含 MIME 类型的 Data URI：

```text
data:image/jpeg;base64,文件的完整Base64编码
```

然后作为 `images` 数组中的字符串发送。视频、音频分别放入 `videos`、`audios`。不能只发裸 Base64，也不能把 `C:\images\cat.jpg`、`file://...`、`blob:...` 当作素材地址。

Python 构造图片字段示例（仅构造请求，不会提交任务）：

```python
import base64
from pathlib import Path

image = base64.b64encode(Path("reference.jpg").read_bytes()).decode("ascii")
payload = {
    "model": "seedance2.5",
    "prompt": "让图片中的主体自然运动，镜头缓慢推进。",
    "duration": 4,
    "resolution": "480p",
    "ratio": "16:9",
    "images": ["data:image/jpeg;base64," + image],
}
```

内联文件会被转换为生成服务可以访问的素材引用；用于处理视频、音频的临时素材链接不应当作永久存储。请仅提交适合交给生成服务处理的素材。

### 需要结构化素材时：content

新用户优先使用 `images` / `videos` / `audios`。已有工作流使用结构化消息时，可改用以下 `content`，**不要再重复发送相同素材数组**：

```json
{
  "model": "seedance2.5",
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "content": [
    {"type": "text", "text": "参考图片中的主体，镜头缓慢推近。"},
    {"type": "image_url", "image_url": {"url": "https://YOUR_PUBLIC_MEDIA_HOST/reference.jpg"}, "role": "reference_image"}
  ]
}
```

视频对应 `type: "video_url"`、`video_url: {"url": "..."}`、`role: "reference_video"`；音频对应 `audio_url` 和 `reference_audio`。`role` 可以省略；填写时必须与媒体类型一致。`url` 对象仅包含 `url`，不要添加聊天图片接口的 `detail` 等字段。

## 7. 查询任务并拿到视频

```bash
curl --fail-with-body \
  "https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID" \
  -H "Authorization: Bearer $ARUHUB_API_KEY"
```

使用创建时的密钥和返回的任务 ID。建议每 5 秒查询一次，根据负载逐步增加到 10～15 秒。不要用循环 POST 替代 GET 轮询。

| `status` | 客户端该怎么做 |
| --- | --- |
| `queued` | 等待排队，稍后继续查同一个 ID |
| `in_progress` | 正在生成，稍后继续查同一个 ID |
| `completed` | 读取视频地址并下载 |
| `failed` | 读取 `error.message`，停止轮询并显示原因 |
| 未识别状态 | 保存原始响应和任务 ID，显示待确认；不要自动重建任务 |

成功响应示意：

```json
{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "seedance2.5",
  "status": "completed",
  "progress": 100,
  "video_url": "https://YOUR_RESULT_HOST/result.mp4",
  "metadata": {"url": "https://YOUR_RESULT_HOST/result.mp4"}
}
```

解析时使用 **`video_url || metadata.url`**。外部成片 URL 不需要携带 AruHub 密钥，不要把密钥转发给视频托管域名。成片地址可能包含有效期信息，完成后应尽快保存到自己的存储。

**不要只保存提示词或网页卡片 ID。** 保存创建返回的本地任务 `id`，页面刷新、程序退出或网络恢复后继续查询这个 ID。更多断线恢复和下载示例见 [共用接入文档](https://docs.aruhub.com/guide/video-api)。

## 8. 常见问题

| 现象 / 报错 | 检查与处理 |
| --- | --- |
| 找不到 `seedance2.5` | 检查密钥可见的 `/v1/models`，确认模型权限和完整拼写，不自行加后缀 |
| `unsupported Seedance option ...` | 删除不属于本教程的参数；不要照搬其他供应商的 `seed`、`watermark`、`negative_prompt`、`generate_audio`、`callback_url` |
| `conflicting duration fields` | 只保留一个时长字段，或确保所有别名值一致 |
| `size and resolution disagree` | 删除非必要 `size`，或让尺寸、分辨率和比例完全一致 |
| 提示 4～30 秒或数量超限 | 检查实际发出的 JSON，不只看界面选项；确认数字是整数 |
| 素材 URL 无效 | 用未登录环境检查直链是否返回真实文件；本地路径和浏览器 blob 地址不可作为公网 URL |
| 图片上传失败 | 检查真实格式、MIME 类型、文件完整性与大小；HEIC 等先转换 |
| 413 / 请求过大 | 减小素材，减少数量或改用公网 URL；同时检查 Base64 膨胀和中间代理的限制 |
| 已生成但自己网站没视频 | 检查是否实现 GET 轮询、保存本地 ID，并兼容读取 `metadata.url` |
| completed 但下载失败 | 只重试查询 / 下载，确认成片 URL 有效；不要重新提交生成 |
| 想等待 webhook 通知 | 当前推荐链路不提供完成回调，客户端实现轮询 |
| 上传了音频但结果不符合预期 | 音频是参考输入，不是确定性的配音 / 音轨合成接口 |

## 9. 提示词怎么写更容易控制

建议按“主体 + 动作 + 场景 + 镜头 + 光线 / 风格 + 需要保持的特征”组织。短片先描述一个明确动作；长片可描述连贯的先后变化，避免在 4 秒内要求多个复杂场景切换。

- 产品展示：`参考图片中的香水瓶，保持瓶身文字和形状。镜头从侧面缓慢移动到正面，柔和侧光，背景简洁，动作平稳。`
- 人像动效：`保持参考人物外观和服装，人物轻微转头并自然微笑，固定镜头，背景不发生明显变化。`
- 风景短片：`清晨山谷薄雾流动，阳光逐渐照亮山脊，镜头缓慢向前，画面稳定，写实风格。`

提示词表达期望，不构成像素级一致性、文字保真、声音效果或镜头精确执行的保证。

## 10. 交给 AI 的配置指令

复制下面整段给负责配置软件或编写代码的 AI。真实密钥在你的本地设置中填写，不要直接写进对话和源码。

```text
请按 AruHub 当前文档接入 Seedance 2.5 视频：
https://docs.aruhub.com/guide/seedance-2-5
https://docs.aruhub.com/guide/video-api

目标模型：seedance2.5。不要自行改成 seedance-2.5 或添加分辨率后缀。
API 根地址：https://api.aruhub.com。
密钥从环境变量 ARUHUB_API_KEY 读取；检查该密钥的 /v1/models 是否包含目标模型。
新代码使用 POST /v1/videos 创建，GET /v1/videos/{创建返回的 id} 查询。
最小请求：model、prompt、duration:4、resolution:"480p"、ratio:"16:9"。
后续时长范围 4～30 秒；本文推荐分辨率 480p/720p。
图片用 images、视频用 videos、音频用 audios 数组。
素材可使用公网直链、带 MIME 的 Base64 Data URI 或 multipart 实际文件。
图片最多30张、视频10个、音频10段；单图20MiB、单视频/音频50MiB；
全部内联素材合计50MiB，请求体72MiB。不要把本地路径直接当作公网URL。
创建后立即持久保存 id，不把上游ID、网页ID或 data.id 当成本站任务ID。
轮询 queued/in_progress，completed 时取 video_url 或 metadata.url，failed 时显示 error.message。
外部视频URL下载不得携带 AruHub 密钥；断线恢复继续查原任务，不自动重发创建请求。
没有完成webhook；不使用聊天/图片接口、不使用stream=true、不编造首尾帧或视频编辑能力。
如果软件自动追加 /v1/videos，Base URL 填根域名；若只追加 /videos，填根域名加 /v1。
如软件仅支持聊天或图片，请明确说明需要新增异步视频工具，不能只填模型名冒充已完成。
先完成配置和无生成验证，展示最终请求地址与脱敏JSON；用户确认试运行后只提交一次最小任务。
交付应包含：实际配置文件位置、启动方式、任务ID持久化方式、查询恢复方式和下载位置。
```

[下载 AI 可读的完整接入说明](https://docs.aruhub.com/downloads/aruhub-video-ai-guide.md) · [Python / Node.js 可运行示例](https://docs.aruhub.com/guide/video-api#可运行脚本与断线续查) · [Grok 视频教程](https://docs.aruhub.com/guide/grok-video)


---


# Grok 视频

本文介绍通过 AruHub 调用 **`grok-imagine-video`** 与 **`grok-imagine-video-1.5`**。接口核对日期：2026-10-31。聊天与图片模型请看 [Grok 聊天与图片](https://docs.aruhub.com/guide/grok)。

**Grok 视频使用异步视频接口。** 客户端先创建任务，再查询本站任务 ID；完成后通过返回的地址下载视频。`/chat/completions`、`/images/generations` 不适用于本文的视频请求。

## 1. 客户端应该怎么填

| 项目 | 填写内容 |
| --- | --- |
| API 根地址 | `https://api.aruhub.com` |
| 仅追加 `/videos` 的 SDK Base URL | `https://api.aruhub.com/v1` |
| 完整创建接口 | `POST https://api.aruhub.com/v1/videos` |
| 完整查询接口 | `GET https://api.aruhub.com/v1/videos/{task_id}` |
| 模型 | `grok-imagine-video` 或 `grok-imagine-video-1.5`，以密钥可用列表为准 |
| 密钥 | 自己的 AruHub API Key |
| 鉴权 | `Authorization: Bearer YOUR_API_KEY` |
| 请求体 | JSON，`Content-Type: application/json` |

密钥需要有目标模型权限。先用 `GET /v1/models` 查询 `data[].id`，不要把聊天模型、图片模型或简称 `grok` 填进视频请求。

::: warning AruHub 入口与 xAI 原生入口不同
本教程客户端使用 `/v1/videos` 创建任务。**不要把 xAI 原生的 `/v1/videos/generations` 直接套到 AruHub 地址上。** AruHub 的另一套兼容入口是单数的 `/v1/video/generations`，它有不同的查询包装结构。详细区别见 [两套协议对照](https://docs.aruhub.com/guide/video-api#两套协议对照)。
:::

### Studio 配置

1. 打开 [AruHub Studio](https://studio.aruhub.com)，在设置的视频模型配置中新增模型。
2. 协议选 **New API**，Base URL 填 `https://api.aruhub.com`，填入自己的 AruHub 密钥。
3. 获取并选择 `grok-imagine-video` 或 `grok-imagine-video-1.5`，保存。
4. 进入视频工作台，先用 **6 秒、480p、16:9、纯文本** 验证；等待完成后预览、下载。

这里选择 New API 是为了使用 AruHub 的兼容任务接口。Studio 中的 **xAI Videos** 模板面向原生 xAI 协议，不应仅替换为 AruHub 域名就直接使用。通用面板显示的时长、素材数量或分辨率也不等于 Grok 全部支持。

## 2. 参数和能力边界

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string，必填 | `grok-imagine-video` / `grok-imagine-video-1.5` |
| `prompt` | string，必填 | 非空提示词 |
| `duration` | integer，必填 | 1～15 秒的整数；推荐首次用 `6` |
| `resolution` | string，建议必填 | 首次用 `480p`；常规可选 `720p`；不要默认所有模型与输入模式都支持 1080p |
| `aspect_ratio` | string，建议必填 | 首次用 `16:9`，竖屏用 `9:16`；常用值还包括 `1:1`、`4:3`、`3:4`、`3:2`、`2:3` |
| `image` | object，可选 | 单张参考图，格式为 `{"url":"公网图片直链"}` |
| `n` | integer，可省略 | 仅接受 `1`，每个请求创建一个视频任务 |

**Seedance 使用 `ratio`，Grok 推荐使用 `aspect_ratio`。** 不要把两种模型的字段直接混用。`duration` 必须明确给出，不依赖上游默认时长。

兼容字段包括 `seconds` / `duration_seconds`、`size` 和部分 `metadata` 字段，但新代码只使用上表中的顶层参数。多个时长、分辨率字段同时出现时必须一致；不一致会返回 `conflicting ... fields`。

### 关于 1080p、图生视频和高级功能

- 当前适配层接受 `480p`、`720p`、`1080p` 字段值；上游能否执行，还取决于具体模型、输入模式和当前服务能力。不要把“参数校验通过”当成生成成功。
- 已有生产成功记录包含 `grok-imagine-video` 的 6 秒 480p 文生视频，以及 `grok-imagine-video-1.5` 的 6 秒 720p 文生视频。本文没有额外验证所有分辨率、比例与素材组合。
- 当前单图 JSON 请求已具备字段转换支持；本次未做真实图生视频验收。建议在文生视频跑通后，单独验证图片场景。
- 当前 Grok 接入不支持 multipart 文件上传、多图、参考视频、参考音频、remix、续写、视频编辑、首尾帧或关键帧接口。没有完成 webhook。
- 不要发送 `parameters`、`width`、`height`，这些字段在当前适配器中明确被拒绝。也不要照搬 Seedance 的 `videos`、`audios`、`mode` 等字段；没有明确支持的字段不能假设会生效。

## 3. 文生视频请求

以下为 Bash 命令；先设置 `ARUHUB_API_KEY`。Windows 用户使用 [PowerShell 版本](https://docs.aruhub.com/guide/video-api#windows-powershell)。

```bash
curl --fail-with-body --max-time 180 \
  https://api.aruhub.com/v1/videos \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "grok-imagine-video",
    "prompt": "A small red ball rests on a wooden table. Static camera, gentle daylight, subtle natural movement.",
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }'
```

提示词也可以使用中文。若选择 1.5，修改 `model` 为 `grok-imagine-video-1.5`，其余异步处理流程相同；不要因模型名变了而改用另一套端点。

创建响应示意：

```json
{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued"
}
```

立即持久保存顶层 `id`。本教程返回的是 AruHub 本地任务 ID，**不是 xAI 原生的 `request_id`**。不要等待创建响应中的 `video.url`，也不要根据 xAI 示例改成轮询上游任务 ID。

## 4. 单图参考请求

先把图片放到生成服务可读取的公网地址，再添加 `image`：

```json
{
  "model": "grok-imagine-video",
  "prompt": "保持参考图主体外观，主体自然轻微运动，镜头缓慢推近。",
  "duration": 6,
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "image": {"url": "https://YOUR_PUBLIC_MEDIA_HOST/reference.jpg"}
}
```

占位地址必须替换为真实图片直链。当前文档推荐公网 HTTPS 图片 URL，不把裸 Base64、Data URI、本地路径或 multipart 当作已验证的 Grok 上传方式。需要从电脑选图时，先由你自己的后端 / 对象存储上传，得到可访问 URL，再提交上述 JSON。

兼容层还可读取 `input_reference` 或单元素 `images` 数组，但不要同时发送多种字段；多张图片或互相冲突的图片引用会被拒绝。

## 5. 轮询任务状态

```bash
curl --fail-with-body \
  "https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID" \
  -H "Authorization: Bearer $ARUHUB_API_KEY"
```

每 5 秒查询一次，后续可增加到 10～15 秒。`queued` / `in_progress` 继续等待，`failed` 读取 `error.message`，`completed` 才开始取片。`progress` 只是进度信息，不应替代 `status` 判断完成。

完成响应示意：

```json
{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "/v1/videos/YOUR_LOCAL_TASK_ID/content"
  }
}
```

**当前 Grok 的成片地址可能只在 `metadata.url`，顶层 `video_url` 可以不存在。** 通用客户端使用 `video_url || metadata.url`，并允许结果是以 `/` 开头的相对路径。

相对路径必须相对于 API 根域名解析。例如：

```text
返回：/v1/videos/YOUR_LOCAL_TASK_ID/content
实际下载：https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID/content
```

不要解析到 `docs.aruhub.com`、你自己的网站域名或 `studio.aruhub.com`。JavaScript 可使用 `new URL(resultUrl, "https://api.aruhub.com")`。

## 6. 鉴权下载与网页播放

下载本站 `/v1/videos/{id}/content` 时，使用自己的 AruHub API Key：

```bash
curl --fail-with-body --max-time 300 \
  "https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID/content" \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  --output grok-result.mp4
```

这是二进制响应，不是 JSON。通常是 `video/mp4`；内容接口可能返回 **HTTP 200 或 206**，206 是分段传输状态，不能直接判为生成失败。自建下载器应核对 `Content-Range` 与实际字节数，避免把不完整分段当作完整文件保存。

### 为什么浏览器直接打开链接会失败

`<video src="...">` 和普通地址栏访问通常不会自动携带 `Authorization: Bearer ...`。因此任务已完成，仍可能出现播放器 401 / 403 或空白。

自建网站推荐采用下面的结构：

1. 前端只把生成参数和你网站自己的用户身份传给后端。
2. 后端持有 AruHub 密钥，创建、轮询并保存任务归属。
3. 完成后，后端鉴权读取本站 content 接口，把视频保存到你的对象存储，或通过你自己的受保护接口流式转发。
4. 前端播放器使用你网站自己的视频地址或短时授权地址。需要拖动进度时，后端正确转发 Range / Content-Range。

个人本地工具也可在自己的运行环境中鉴权下载，再生成本地 Blob URL 播放。不要把公共网站后端的共享密钥打包到前端代码，也不要把密钥拼成 `?api_key=...` 放进下载地址。

视频 URL 若指向外部托管域名，下载时**不要转发 AruHub 密钥**。只向 `https://api.aruhub.com` 的本站接口发送该密钥，下载重定向到外部域名时同样需要移除鉴权头。

## 7. 错误与恢复

| 现象 / 报错 | 应对方式 |
| --- | --- |
| `/v1/videos/generations` 返回 404 | 使用 AruHub 的 `/v1/videos`；不要混入原生 xAI 创建路径 |
| `xAI video requires an application/json request` | 发送 JSON；不要上传 multipart 文件 |
| `duration or seconds is required` | 明确填写顶层 `duration`，范围 1～15 秒 |
| `conflicting duration/resolution fields` | 清理客户端自动附加的 `seconds`、`size`、`metadata` 等冲突项 |
| `xAI video does not accept parameters/width/height` | 删除对应字段，改用顶层 `duration`、`resolution`、`aspect_ratio` |
| `xAI video accepts a single input image` | 只保留一张参考图，不发送多图数组 |
| completed 但 `video_url` 为空 | 读取 `metadata.url`，这是当前 Grok 正常返回方式 |
| 下载地址以 `/v1/...` 开头 | 相对于 `https://api.aruhub.com` 解析 |
| content 接口 401 / 403 | 检查是否发送自己的 AruHub Bearer 密钥，任务是否属于该身份 |
| content 接口 206 | 按视频分段响应处理，检查范围；不要当作生成失败 |
| 轮询时临时 429 / 5xx | 延迟后继续 GET 原任务；不要 POST 新任务 |
| 审核或生成失败 | 读取错误原因，停止该任务轮询，修改内容后由用户决定是否重新提交 |
| `invalid api platform: 48` | 保留任务时间、模型和脱敏报错联系支持，不通过乱改协议或模型名反复重试 |
| 页面刷新后丢了视频任务 | 客户端应持久化本地任务 ID，恢复时继续查询，不重新创建 |

## 8. 交给 AI 的配置指令

```text
请为我的软件接入 AruHub Grok 视频，先阅读：
https://docs.aruhub.com/guide/grok-video
https://docs.aruhub.com/guide/video-api

API根地址：https://api.aruhub.com。
模型使用 grok-imagine-video 或 grok-imagine-video-1.5，以 ARUHUB_API_KEY 可见的模型为准。
密钥从环境变量读取，不写进源码或公开前端。
新代码 POST /v1/videos 创建，GET /v1/videos/{创建返回的本地id} 查询。
不要使用原生xAI的 /v1/videos/generations，不使用聊天或图片接口。
最小JSON：model、prompt、duration:6、resolution:"480p"、aspect_ratio:"16:9"。
时长1～15秒整数；先验证480p，再尝试目标模型支持的其他组合。
仅单图参考：image:{"url":"公网图片直链"}；不使用multipart、多图、参考音视频、remix或编辑。
创建后立即持久保存顶层id；每5秒GET查询，适当退避。
queued/in_progress继续等待；failed显示error.message；completed读取video_url或metadata.url。
Grok可能只返回metadata.url，且值为 /v1/videos/{id}/content。
相对路径解析到API根域名；本站content下载携带自己的AruHub密钥。
外部视频URL和跨域重定向不得收到AruHub密钥。不要将密钥放进URL查询参数。
content是二进制视频，200/206都需正确处理；检查完整性后保存文件。
网页播放器通过自己的后端鉴权代理或保存后的媒体地址播放，不能假设video标签会带Bearer头。
没有完成webhook；GET临时失败可退避重试，POST创建超时不自动重发。
先做配置和无生成验证，展示实际请求地址与脱敏JSON；用户确认试运行后提交一次最小任务。
交付配置文件位置、启动命令、任务ID保存/恢复方式、视频下载位置和异常处理。
```

[下载 AI 可读的完整接入说明](https://docs.aruhub.com/downloads/aruhub-video-ai-guide.md) · [可运行 Python / Node.js 示例](https://docs.aruhub.com/guide/video-api#可运行脚本与断线续查) · [Seedance 2.5 视频](https://docs.aruhub.com/guide/seedance-2-5)