Query & download

GET /v1/videos/{id}

Poll GET /v1/videos/{id} for the latest status. On completion (status=completed) the gateway injects output_url = {base}/v1/videos/{task_id}/content — one stable URL regardless of where the upstream put the result.

Query response (after completion)

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "created_at": 1700000000,
  "completed_at": 1700000060,
  "output_url": "https://us.gsnails.xyz/v1/videos/task_xxxxxxxx/content"
}

Download

GET /v1/videos/{id}/content

Once complete, GET /v1/videos/{id}/content streams the binary (image or video); data: URLs are decoded automatically. Returns 400 if not yet complete; client query params are not forwarded.

State machine

queued → in_progress (progress 0~100) → completed | failed. Finish polling only on a terminal status; failed tasks are fully refunded.

Full polling example

import time, requests
BASE = "https://us.gsnails.xyz/v1"
KEY  = "sk-..."
H = {"Authorization": f"Bearer {KEY}"}
1) create — returns a queued task
job = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "gpt-image-2",
    "prompt": "a neon fox",
    "tier": "2k",
}).json()
task_id = job["id"]
2) poll until the task reaches a terminal state
while job["status"] not in ("completed", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
3) download via the unified output_url
if job["status"] == "completed":
    url = job["output_url"]            # = {BASE}/videos/{id}/content
    open("out.bin", "wb").write(requests.get(url, headers=H).content)