从一个提示词，
到一条视频。

连接与鉴权

每个 API 请求携带 Authorization: Bearer <key>。key 不放在 URL、提示词或项目字段中。你拿到的是 Studio 访问 key，无需配置 Grok 供应商密钥。

export STUDIO_URL='https://video-gen.qianyiyule.top'
# 下一行等待输入 key，输入时不会显示；按回车确认。
read -r -s STUDIO_ACCESS_KEY
export STUDIO_ACCESS_KEY

curl -sS "$STUDIO_URL/api/health" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY"

正常返回包含 ok: true 和 backends。后端的 state 表示就绪状态。模型探测成功不代表一次新生成已完成。

网页从 登录页 输入相同 key，保存 30 天会话。API 继续使用 Bearer 即可，不必先登录。浏览器应用应同源调用；第三方网页跨域暂未启用，服务端和脚本可直接调用。

选择生成后端

画幅由项目的 aspect 指定：16:9、9:16 或 1:1。实际像素取决于后端和画幅，以任务 params.width / height 为准。不指定画质时，接口默认 high；下面入门示例显式使用本地 fast。

查询 GET /api/backends 获取当前能力。Grok 的 hidden: true 仅表示不自动分配，显式指定仍可使用。费用估算看 capabilities.cost_usd_per_s，最终费用看完成任务的 cost_usd；为空时表示尚无费用记录。

生成第一条视频

入门使用 single_shot 模板，没有人工审核门。其他模板可能需要剧本或关键帧审核，不能照搬无审核的提交过程。

推荐：直接运行 Python 示例

只需要 Python 3，无第三方依赖。脚本会创建项目、生成一个 5 秒镜头、每 10 秒查询状态，完成后下载 MP4 并校验 SHA-256。运行即会提交真实生成任务。

# 先按“连接与鉴权”设置 STUDIO_ACCESS_KEY。
curl -fsS "$STUDIO_URL/api/guide/example.py" -o generate_video.py
export STUDIO_BACKEND=win-4060ti
export STUDIO_QUALITY=fast
export STUDIO_SECONDS=5
python3 generate_video.py

export STUDIO_BACKEND=grok-cloud
export STUDIO_QUALITY=high   # 720p；ultra 为 1080p
export STUDIO_SECONDS=5
python3 generate_video.py

可选环境变量：STUDIO_PROMPT 设置提示词，STUDIO_AUTHOR 设置作者名。每次执行会创建一个新项目；连接中断时先查看本地 api-demo-*-request.json 中的 job_id，不要直接重跑脚本。

PROJECT="api-demo-$(date +%s)"
curl -sS "$STUDIO_URL/api/projects" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"id\":\"$PROJECT\",\"title\":\"我的第一条视频\",\"template\":\"single_shot\",\"aspect\":\"16:9\",\"by\":\"member\"}"

REV=$(curl -sS "$STUDIO_URL/api/projects/$PROJECT" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" | jq -r '.revision')

curl -sS -X PUT "$STUDIO_URL/api/projects/$PROJECT/shots" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" \
  -H 'Content-Type: application/json' -H "If-Match: $REV" \
  -d '{"by":"member","shots":[{"no":1,"seconds":5,"prompt":"A quiet lake at sunrise, gentle ripples, slow camera push in. No dialogue, no music."}]}'

REV=$(curl -sS "$STUDIO_URL/api/projects/$PROJECT" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" | jq -r '.revision')
IDEM=$(python3 -c 'import uuid; print(uuid.uuid4())')

curl -sS "$STUDIO_URL/api/projects/$PROJECT/render" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $REV" -H "Idempotency-Key: $IDEM" \
  -d '{"shots":[1],"backend":"win-4060ti","quality":"fast","by":"member"}' \
  | tee render-response.json

JOB=$(jq -r '.jobs[0].id' render-response.json)
curl -sS "$STUDIO_URL/api/jobs/$JOB" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY"

图片、首尾帧与中间关键帧

先上传素材，再在镜头中引用返回的逻辑路径。上传使用 multipart，path 只能位于 assets/、blockout/ 或 keyframes/ 下。最大单文件 2 GiB，并校验真实文件格式。

REV=$(curl -sS "$STUDIO_URL/api/projects/$PROJECT" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" | jq -r '.revision')
curl -sS "$STUDIO_URL/api/projects/$PROJECT/files" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" -H "If-Match: $REV" \
  -F 'path=keyframes/first.png' -F 'file=@first.png' -F 'by=member'

上传后重新获取项目 revision，再写入镜头。以下是镜头字段示意，各路径都必须先上传：

{
  "no": 1,
  "seconds": 8,
  "prompt": "A smooth camera movement through the scene.",
  "first_frame": "keyframes/first.png",
  "last_frame": "keyframes/last.png",
  "keyframes": [{"frame": "keyframes/middle.png", "at": 4}]
}

本地 H3 支持首帧和首尾帧。中间关键帧目前仅 Grok 支持，最多 4 张，at 必须严格递增且位于镜头起止之间。continue_from 可引用上游镜头编号，从上游选定版本提取承接帧。

查询状态与下载结果

生成接口立即返回任务信息，HTTP 连接不会一直等待 GPU。轮询 GET /api/jobs/{job_id}，建议间隔 5～10 秒。

curl -sS "$STUDIO_URL/api/projects/$PROJECT/shots" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" > shots-response.json

# 获取 JOB 对应版本的 file 字段，避免误下载其他成员选定的版本。
FILE=$(jq -r --arg job "$JOB" \
  '.shots[].versions[] | select(.job_id == $job) | .file' shots-response.json)
curl -fS "$STUDIO_URL/api/projects/$PROJECT/files/$FILE" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY" -o result.mp4

文件接口支持 Range 和 ETag。下载项目当前选定的全部文件可用 GET /api/projects/{id}/manifest，其中 files[].url 相对于 /api，需要拼为 $STUDIO_URL/api + url。

curl -N -sS "$STUDIO_URL/api/events?project=$PROJECT&after=0" \
  -H "Authorization: Bearer $STUDIO_ACCESS_KEY"

接口速查

下表路径均相对于 /api。完整字段可在登录后查看 交互式接口文档 和 OpenAPI JSON。

render 可用字段：shots（编号数组或 "all"）、backend、quality、versions（如 {"1":2}，表示第 1 镜生成两版）、priority、by。多版本会提交多次生成，Grok 相应增加费用。

错误、并发与重试

业务错误通常返回 {"error":{"code":"…","message":"…","details":{}}}；参数校验也可能返回 {"detail":[…]}。

If-Match 是并发保护，填写你刚读取的 revision。它不是身份凭据，也不是幂等键。上传、镜头改动和选版会推进 revision，不能长期固定使用一个数字。