Videos

The /v1/videos endpoint initiates asynchronous video generation jobs from descriptive text prompts across cutting-edge video synthesis models like Google Veo and OpenAI Sora. Because video generation is compute-intensive and requires prolonged rendering times, nRouter provides an asynchronous job lifecycle: requests return an immediate sealed job ID, followed by status polling via GET /v1/videos/{id} and binary download via GET /v1/videos/{id}/content.

POST https://api.nrouter.ai/v1/videos

Architectural Role & Asynchronous Lifecycle

Video synthesis workflows span multiple seconds or minutes of GPU processing. nRouter handles video workloads through a three-stage asynchronous pattern:

sequenceDiagram
    autonumber
    Client->>Gateway: POST /v1/videos (prompt, model, seconds)
    Note over Gateway: Preflight: Key Auth, Rate Limits, Guardrails, Credit Hold
    Gateway-->>Client: HTTP 200 { id: "nrouter_video_abc123", status: "queued" }
    loop Poll Progress
        Client->>Gateway: GET /v1/videos/nrouter_video_abc123
        Gateway-->>Client: HTTP 200 { status: "processing", progress: 65 }
    end
    Client->>Gateway: GET /v1/videos/nrouter_video_abc123
    Gateway-->>Client: HTTP 200 { status: "completed" }
    Client->>Gateway: GET /v1/videos/nrouter_video_abc123/content
    Gateway-->>Client: HTTP 200 (video/mp4 binary stream)

1. Phase 1: In-Memory Validation: Verifies virtual key hash (sk-nrouter-...) and checks tenant permissions for the target video generation model.
2. Phase 2: Concurrency & Rate Limit Validation: Validates that the organization has available concurrent video rendering slots.
3. Phase 3: Content Moderation & Injection Screening: Inspects the descriptive prompt against safety classifiers and prompt injection defenses. Blocked prompts halt with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Duration Credit Reservation: Places an atomic hold based on requested duration (seconds) and resolution tier. Zero credits are held on preflight failures.
5. Upstream Job Dispatch: Registers the job with the upstream provider and returns a sealed job object (nrouter_video_...).

Request Parameters

The request body must be a JSON object:

Response Payloads

Immediate Job Creation Response

{
  "id": "nrouter_video_01j89azxckm3287",
  "object": "video.generation",
  "status": "queued",
  "created": 1709251200,
  "model": "veo-2.0"
}

Response Field Breakdown

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

// 1. Submit video generation job
const job = await client.videos.create({
  model: "veo-2.0",
  prompt: "Cinematic drone shot soaring over mist-covered pine forests at dawn.",
  seconds: 5,
  size: "1280x720",
});

console.log(`Video job initiated: ${job.id} (Status: ${job.status})`);

Error Handling & Troubleshooting

{
  "error": {
    "type": "gateway_error",
    "message": "Requested duration of 30 seconds exceeds maximum supported duration of 10 seconds.",
    "code": "invalid_request"
  }
}

curl -X POST "https://example.com/v1/videos" \  -H "Content-Type: application/json" \  -d '{    "model": "string",    "prompt": "string"  }'

{  "id": "nrouter_video_abc123",  "object": "video.generation",  "status": "queued"}