跳到主要内容

Grok Video Authenticated Result URL Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Update the Grok video API page so clients retrieve successful videos from the gateway's authenticated local result_url instead of treating it as a public temporary MP4 link.

Architecture: Keep the existing create and polling workflow unchanged. Correct only the documentation contract, examples, JavaScript download flow, and troubleshooting text in the existing Grok page, then validate the page with targeted assertions and the repository's documentation build commands.

Tech Stack: Docusaurus 3, Markdown/MDX, Node.js 20+

Global Constraints​

  • Modify docs/api文档/grok-视频-api配置.md only for product-facing behavior.
  • Keep POST /v1/video/generations and GET /v1/video/generations/{task_id} unchanged.
  • Document data.result_url as an authenticated local proxy URL.
  • Every video content request must send Authorization: Bearer <YOUR_API_KEY>.
  • Explain that source video resources are typically retained for about one hour and should be downloaded or persisted within one hour of task success.
  • Do not document raw provider task data or provider-hosted media URLs.

Task 1: Align the Grok video result URL contract​

Files:

  • Modify: docs/api文档/grok-视频-api配置.md:8-487

Interfaces:

  • Consumes: Successful task responses from GET /v1/video/generations/{task_id}.

  • Produces: Copyable curl and JavaScript examples that authenticate requests to data.result_url.

  • Step 1: Run the contract assertion against the current page and verify it fails

Run:

node <<'NODE'
const fs = require('node:fs')
const path = 'docs/api文档/grok-视频-api配置.md'
const text = fs.readFileSync(path, 'utf8')
const required = [
  'https://api.constreet.cc/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content',
  '`result_url` 是受鉴权保护的本站视频代理地址',
  'Authorization: Bearer <YOUR_API_KEY>',
  'async function downloadVideo(videoUrl)',
  '401（视频下载）',
]
const forbidden = ['临时直链', '有效期约 1 小时']
const missing = required.filter((value) => !text.includes(value))
const presentForbidden = forbidden.filter((value) => text.includes(value))
if (missing.length || presentForbidden.length) {
  console.error({ missing, presentForbidden })
  process.exit(1)
}
NODE

Expected: FAIL. The output lists the authenticated proxy copy and JavaScript helper as missing, and lists the temporary-link claims as forbidden text still present.

  • Step 2: Update the endpoint summary and successful response example

Add the content endpoint to the basic information table:

| 获取视频内容 | `GET /v1/videos/{task_id}/content` |

Use the authenticated local proxy in the successful response:

"result_url": "https://api.constreet.cc/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"

Immediately after the success example, state:

`result_url` 是受鉴权保护的本站视频代理地址，不是公开文件直链。下载或播放视频时仍须携带创建任务时使用的 API Key；在没有登录态或 `Authorization` 请求头的浏览器中直接打开，通常会返回 HTTP 401。
  • Step 3: Replace the unauthenticated curl download example

Use this command:

curl -L \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -o "grok_video_$(date +%s).mp4" \
  "$result_url"

Replace the temporary-link warning with:

`result_url` 由本站代理视频内容。它不是可公开分享的裸链接，每次请求都应携带 API Key。建议由服务端下载、转存或转发给最终用户，不要把 API Key 放入浏览器前端代码。
  • Step 4: Add an authenticated JavaScript download helper

Add this function after sleep:

async function downloadVideo(videoUrl) {
 const response = await fetch(videoUrl, {
   headers: {
     Authorization: `Bearer ${API_KEY}`,
   },
 })

 if (!response.ok) {
   throw new Error(`Video download failed with HTTP ${response.status}`)
 }

 return response.arrayBuffer()
}

After createVideo, add a server-side usage example:

const video = await createVideo({
 prompt: 'A cinematic sunrise over a futuristic city',
})
const videoBytes = await downloadVideo(video.video_url)

State that videoBytes can be saved or returned by the user's backend, and that the API key must not be exposed in browser code.

  • Step 5: Update troubleshooting and integration notes

Add this troubleshooting row:

| 401（视频下载） | 请求 `result_url` 时未携带 API Key | 在视频请求中增加 `Authorization: Bearer <YOUR_API_KEY>` |

Replace the final temporary-link note with:

* 最终视频地址位于查询接口的 `data.result_url`。该地址是受鉴权保护的本站代理接口，下载或播放时必须携带 `Authorization: Bearer <YOUR_API_KEY>`。
  • Step 6: Re-run the contract assertion and verify it passes

Run the Step 1 command again.

Expected: PASS with exit code 0 and no output.

  • Step 7: Run repository documentation checks

Run:

npm run check:docs
npm run build
git diff --check

Expected: all commands exit 0. Docusaurus reports a successful production build, and git diff --check produces no output.

  • Step 8: Commit the documentation change
git add docs/api文档/grok-视频-api配置.md docs/superpowers/plans/2026-07-17-grok-video-authenticated-result-url.md
git commit -m "docs: clarify authenticated Grok video downloads"

Task 2: Clarify source video retention​

Files:

  • Modify: docs/api文档/grok-视频-api配置.md
  • Modify: docs/superpowers/specs/2026-07-17-grok-video-authenticated-result-url-design.md

Interfaces:

  • Consumes: The authenticated local result_url contract from Task 1.

  • Produces: A retention warning that applies to the source resource without mislabeling the local proxy URL as a public temporary link.

  • Step 1: Run a failing contract assertion

Require the Grok page to contain both 视频源文件通常仅保留约 1 小时 and 建议在任务成功后 1 小时内完成下载或转存.

  • Step 2: Add the scoped retention warning

State that the local proxy URL remains authenticated while the source resource behind it is typically retained for about one hour, and recommend downloading or persisting the result within one hour of task success.

  • Step 3: Re-run documentation verification

Run the targeted contract assertion, npm run check:docs, npm run build, and git diff --check.