视频 API 接入与 AI 配置

本页是 Seedance 2.5 和 Grok 视频的共用接入说明。接口核对日期：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、用量记录出现，都不能单独证明用户已经收到完整视频。

本页目录（点击展开）

接入准备
两个模型怎么选参数
两套协议对照
Windows PowerShell
可运行脚本与断线续查
工作流工具怎么连
自建网站与 AI Agent
下载与重试规则
通用报错排查
交给 AI 的完整任务模板
接入完成的检查清单

接入准备

从我的密钥获取自己的 AruHub API Key。密钥需具备目标模型权限。
确认工具支持自定义视频接口和异步任务。只支持聊天、图片或同步响应的软件，需要新增视频工具或 HTTP 工作流。
确认模型 ID。本文使用 seedance2.5、grok-imagine-video、grok-imagine-video-1.5，以你的密钥当前可用列表为准。
把密钥放在本地环境变量、工具的凭据管理器或网站后端配置中。公开文档、源码和发送给 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 脚本：Python 3.10+，只使用标准库，无需安装 SDK。
下载 Node.js 脚本：Node.js 20+，使用内置 fetch，无需安装 SDK。
下载 Seedance 示例请求。
下载 Grok 示例请求。

脚本行为：读取 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 教程；本脚本使用 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 视频 · Grok 视频 · 下载 AI 可读说明

视频 API 接入与 AI 配置 ​

接入准备 ​

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

地址填写规则 ​

两个模型怎么选参数 ​

两套协议对照 ​

Windows PowerShell ​

可运行脚本与断线续查 ​

Python 使用方式 ​

Node.js 使用方式 ​

保存文件的含义 ​

请求文件内容 ​

工作流工具怎么连 ​

自建网站与 AI Agent ​

下载与重试规则 ​

通用报错排查 ​

交给 AI 的完整任务模板 ​

接入完成的检查清单 ​

视频 API 接入与 AI 配置

接入准备

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

地址填写规则

两个模型怎么选参数

两套协议对照

Windows PowerShell

可运行脚本与断线续查

Python 使用方式

Node.js 使用方式

保存文件的含义

请求文件内容

工作流工具怎么连

自建网站与 AI Agent

下载与重试规则

通用报错排查

交给 AI 的完整任务模板

接入完成的检查清单