跳到主要内容

Grok Video Authenticated Result URL Design

Goal​

Align the Grok video API documentation with the existing gateway behavior: a successful task returns a local, authenticated video proxy URL instead of a public provider-hosted MP4 URL.

Scope​

  • Update docs/api文档/grok-视频-api配置.md only.
  • Keep the existing POST /v1/video/generations and GET /v1/video/generations/{task_id} workflow.
  • Do not change the API gateway, routes, response structures, models, or other documentation pages.

Public Contract​

  • A successful query returns data.result_url in the form https://api.constreet.cc/v1/videos/{task_id}/content.
  • result_url is an authenticated local proxy endpoint, not a public or temporary provider-hosted file URL.
  • Clients must send Authorization: Bearer <YOUR_API_KEY> when downloading or streaming the video.
  • Opening result_url directly without an authenticated browser session or an Authorization header can return HTTP 401.
  • The local proxy URL is not itself the temporary source link, but the source video resource is typically retained for about one hour. Clients should download or persist the video within one hour of task success.
  • Raw provider response data and provider-hosted media URLs are not part of the documented public contract.

Documentation Changes​

  1. Replace the successful response example's public MP4 URL with the local content proxy URL.
  2. Replace the unauthenticated curl download command with one that sends the API key.
  3. Replace statements that describe result_url itself as a temporary direct link. Clarify that the source resource behind the authenticated proxy is typically retained for about one hour and should be downloaded promptly.
  4. Add a JavaScript helper that downloads the video through result_url with the same Bearer token used for task creation and polling.
  5. Add a troubleshooting row for HTTP 401 during video download.
  6. Repeat the authenticated-proxy requirement in the integration notes so it is not missed when examples are copied selectively.

Error Handling​

  • Task creation and polling errors retain their current handling.
  • The JavaScript download helper checks response.ok and reports the HTTP status when content retrieval fails.
  • The documentation distinguishes task success from successful content download: a SUCCESS task still requires an authenticated request to retrieve its video bytes.

Verification​

  • Run npm run check:docs to validate documentation conventions.
  • Run npm run build to verify the MDX page compiles and the site builds.
  • Search the Grok page to confirm the one-hour retention note refers to the source resource rather than result_url itself.
  • Confirm every content-download example includes the Authorization header.