Skip to main content
GET
/
video
/
status
cURL
curl --request GET \
  --url https://nano-gpt.com/api/video/status \
  --header 'x-api-key: <api-key>'
{
  "requestId": "<string>",
  "status": "queued",
  "videoUrl": "<string>",
  "error": "<string>",
  "createdAt": "<string>",
  "completedAt": "<string>",
  "progress": 123,
  "estimatedTimeRemaining": 123
}

​
Overview

Check the status of an asynchronous video generation job using a single, provider-agnostic endpoint. This endpoint accepts NanoGPT job IDs (vid_...) and legacy provider request IDs. No model parameter is required. Session ownership is enforced (returns 403 when the job is not yours).

​
Query parameters

ParameterTypeRequiredDescription
requestIdstringYes*The job ID (vid_...) or a legacy provider request ID
runIdstringYes*Alias for requestId
*Send either requestId or runId.

​
Authentication

Provide x-api-key or a valid session cookie.

​
Usage

import requests
import time

BASE = "https://nano-gpt.com/api"

def get_video_status(request_id: str, api_key: str) -> dict:
    resp = requests.get(
        f"{BASE}/video/status",
        headers={"x-api-key": api_key},
        params={"requestId": request_id},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

def wait_for_video(request_id: str, api_key: str, max_attempts: int = 120, delay_s: int = 5) -> str:
    for _ in range(max_attempts):
        payload = get_video_status(request_id, api_key)
        status = payload.get("data", {}).get("status")
        if status == "COMPLETED":
            return payload["data"]["output"]["video"]["url"]
        if status == "FAILED":
            raise RuntimeError(payload.get("data", {}).get("error", "Video generation failed"))
        time.sleep(delay_s)
    raise TimeoutError("Video generation timed out")

​
Status values

  • IN_QUEUE: Request queued
  • IN_PROGRESS: Generation in progress
  • COMPLETED: Video ready
  • FAILED: Generation failed
  • CANCELED: Request canceled

​
Response examples

​
In progress

{
  "requestId": "vid_m1abc123def456",
  "model": "sora-2",
  "data": {
    "status": "IN_PROGRESS",
    "requestId": "vid_m1abc123def456"
  }
}

​
Completed

{
  "requestId": "vid_m1abc123def456",
  "model": "sora-2",
  "data": {
    "status": "COMPLETED",
    "requestId": "vid_m1abc123def456",
    "output": {
      "video": {
        "url": "https://storage.example.com/video.mp4"
      }
    },
    "cost": 0.35
  }
}

​
Failed

{
  "requestId": "vid_m1abc123def456",
  "model": "sora-2",
  "data": {
    "status": "FAILED",
    "requestId": "vid_m1abc123def456",
    "error": "Content policy violation",
    "isNSFWError": true,
    "userFriendlyError": "Content flagged as inappropriate. Please modify your prompt and try again."
  }
}
Notes:
  • Terminal results are cached in video_jobs for faster subsequent status checks.

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
requestId
string
required

The unique request ID returned from any video generation endpoint

Response

Unified video generation status

​
requestId
string
required

The unique request ID for the video generation

​
status
enum<string>
required

Current normalized status of the video generation

Available options:
queued,
processing,
completed,
failed,
cancelled,
unknown
​
videoUrl
string | null
required

URL to the generated video (available when status is 'completed')

​
error
string | null
required

Error message if the generation failed

​
createdAt
string | null
required

ISO timestamp when the request was created

​
completedAt
string | null
required

ISO timestamp when the generation completed

​
progress
number | null

Generation progress as a percentage (0-100), if available

​
estimatedTimeRemaining
number | null

Estimated time remaining in seconds, if available