Vidu 文生视频 API 使用说明

本说明基于项目中提供的测试脚本，演示如何通过本服务提交“文生视频（text-to-video）”任务并轮询查询结果。文中示例默认使用项目中 docs/gemini/gemini.md 的 Base URL：https://agentpivot.ai/。

前置条件

• 本服务已配置 Tencent VCLM（model_provider_groups.model=vidu 的 credentials_json 或对应环境变量）。
• 用户账户有足够余额（接口会预检并扣费）。
• 本机已安装 jq（用于解析 JSON，macOS 可通过 brew install jq 安装）。

快速使用（环境变量）

• SECRET_KEY：优先使用，作为 x-api-key 认证。
• AUTH_HEADER：可替代 SECRET_KEY，传入 Authorization: Bearer <jwt>。
• BASE_URL：API 地址，默认 https://api.agentpivot.ai（来自 docs/gemini/gemini.md）。
• VIDU_TEST_MODEL：测试模型，默认 viduq3-pro。
• VIDU_TEST_PROMPT：测试提示（prompt）。
• VIDU_TEST_DURATION：生成视频时长（秒），默认 5。
• VIDU_TEST_RESOLUTION：分辨率，默认 720p。
• VIDU_POLL：非空则轮询查询直到终态或超时。
• VIDU_POLL_MAX：最大查询次数（默认 36）。
• VIDU_POLL_INTERVAL：查询间隔秒（默认 5）。

脚本（示例）

下面为已调整的测试脚本，BASE_URL 默认值指向 https://api.agentpivot.ai：

#!/usr/bin/env bash
# Vidu 文生视频：本服务 POST 提交任务 + GET 查询结果（Tencent VCLM 后端）
# 前置：已配置 VCLM，且用户有足够余额

set -euo pipefail

BASE_URL="${BASE_URL:-https://api.agentpivot.ai}"
BASE_URL="${BASE_URL%/}"
CREATE_URL="${BASE_URL}/ent/v2/text2video"
MODEL="${VIDU_TEST_MODEL:-viduq3-pro}"
PROMPT="${VIDU_TEST_PROMPT:-A cat walking on grass, cinematic, short clip.}"
DURATION="${VIDU_TEST_DURATION:-5}"
RESOLUTION="${VIDU_TEST_RESOLUTION:-720p}"

if [ -n "${SECRET_KEY:-}" ]; then
  AUTH_HDR=(-H "x-api-key: ${SECRET_KEY}")
elif [ -n "${AUTH_HEADER:-}" ]; then
  AUTH_HDR=(-H "Authorization: ${AUTH_HEADER}")
else
  echo "请设置 SECRET_KEY（x-api-key）或 AUTH_HEADER（Bearer JWT）" >&2
  exit 1
fi

if ! command -v jq &>/dev/null; then
  echo "需要 jq（brew install jq）" >&2
  exit 1
fi

BODY=$(jq -n \
  --arg m "$MODEL" \
  --arg p "$PROMPT" \
  --argjson d "${DURATION}" \
  --arg r "$RESOLUTION" \
  '{
    model: $m,
    prompt: $p,
    duration: $d,
    resolution: $r,
    aspect_ratio: "16:9",
    off_peak: false
  }')

echo "== 1) 提交文生视频 =="
echo "POST ${CREATE_URL}"
echo "model=${MODEL} duration=${DURATION}s resolution=${RESOLUTION}"
echo ""

CREATE_RAW=$(curl -sS -m 120 -X POST "${CREATE_URL}" \
  -H "Content-Type: application/json" \
  "${AUTH_HDR[@]}" \
  -d "${BODY}")

echo "${CREATE_RAW}" | jq . 2>/dev/null || echo "${CREATE_RAW}"

TASK_ID=$(echo "${CREATE_RAW}" | jq -r '.task_id // empty' 2>/dev/null || true)
if [ -z "${TASK_ID}" ] || [ "${TASK_ID}" = "null" ]; then
  echo "" >&2
  echo "未拿到 task_id（检查上游报错或 message/status 字段）" >&2
  exit 1
fi

QUERY_URL="${BASE_URL}/ent/v2/tasks/${TASK_ID}/creations"
echo ""
echo "== 2) 查询任务 =="
echo "GET ${QUERY_URL}"
echo ""

query_once() {
  curl -sS -m 60 -X GET "${QUERY_URL}" \
    -H "Content-Type: application/json" \
    "${AUTH_HDR[@]}"
}

if [ -n "${VIDU_POLL:-}" ]; then
  MAX="${VIDU_POLL_MAX:-36}"
  INTERVAL="${VIDU_POLL_INTERVAL:-5}"
  n=0
  while [ "${n}" -lt "${MAX}" ]; do
    n=$((n + 1))
    echo "--- 第 ${n}/${MAX} 次查询（间隔 ${INTERVAL}s）---"
    OUT=$(query_once)
    echo "${OUT}" | jq . 2>/dev/null || echo "${OUT}"
    STATE=$(echo "${OUT}" | jq -r '.state // empty' 2>/dev/null || true)
    if [ "${STATE}" = "success" ] || [ "${STATE}" = "failed" ]; then
      echo ""
      echo "终态: ${STATE}"
      exit 0
    fi
    if [ "${n}" -lt "${MAX}" ]; then
      sleep "${INTERVAL}"
    fi
  done
  echo "已达到最大查询次数，未等到终态（当前 state=${STATE:-unknown}）" >&2
  exit 2
else
  OUT=$(query_once)
  echo "${OUT}" | jq . 2>/dev/null || echo "${OUT}"
fi

关键说明

• 提交接口：POST ${BASE_URL}/ent/v2/text2video，Body 见脚本中 BODY JSON（包含 model、prompt、duration、resolution、aspect_ratio、off_peak 等字段）。
• 查询接口：GET ${BASE_URL}/ent/v2/tasks/{task_id}/creations，由提交响应中的 task_id 提供。
• 超时与重试：脚本中 curl 的 -m 超时时间分别为提交 120s、查询 60s，可根据网路环境调整。
• jq 用于解析 JSON 输出，便于观察 task_id 与 state 字段。

示例：手工使用 curl

1. 提交任务：

curl -X POST "${BASE_URL}/ent/v2/text2video" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model":"viduq3-pro",
    "prompt":"一只小猫在草地奔跑",
    "duration":5,
    "resolution":"720p",
    "aspect_ratio":"16:9",
    "off_peak":false
  }'

2. 查询任务（替换 {task_id}）：

curl -X GET "${BASE_URL}/ent/v2/tasks/{task_id}/creations" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

运行测试脚本

在项目根目录或 packages/api 下运行：

export SECRET_KEY="YOUR_API_KEY"
export VIDU_TEST_PROMPT="一只小猫在草地奔跑"
# 可选： export BASE_URL="https://api.agentpivot.ai"
bash ./packages/api/scripts/test-vidu-text2video.sh

注意事项

• 请勿在公共仓库中提交真实的 API Key。
• 若后端或代理对接口路径或字段有差异，请以服务端返回为准并做相应调整。
• 若需要将脚本集成到 CI 或异地执行，建议增加更完善的错误重试与日志记录。

---

文件位置：docs/vidu/vidu-api.md