Get Video Content

The /v1/videos/{id}/content endpoint streams the raw binary MP4 video stream for a completed video generation request. By returning binary media directly rather than wrapping assets in Base64 JSON strings, nRouter eliminates decoding overhead, reduces client memory consumption, and enables high-throughput streaming playback in media applications.

GET https://api.nrouter.ai/v1/videos/{id}/content

Architectural Role & Lifecycle

When a client requests video content from /v1/videos/{id}/content:

1. Phase 1: In-Memory Key Auth & Tenancy Validation: Authenticates the sk-nrouter-... key and verifies that the video job was created by the caller's tenant organization. If a key from another tenant attempts to download the asset, the gateway returns HTTP 404 Not Found (model_not_found).
2. State Verification: Inspects the rendering lifecycle state:
   • If the job is still queued or processing, the gateway halts with HTTP 400 Bad Request (invalid_request: "Video rendering is still in progress. Please poll /v1/videos/{id} until status is completed.").
   • If the job failed, the gateway returns HTTP 400 Bad Request describing the generation failure.
   • If completed, the gateway initiates a binary media pipe.
3. Binary Stream Pipe: Streams the raw video/mp4 data directly from the storage cache to the client while applying Content-Type: video/mp4 and Content-Disposition headers.
4. Zero Incremental Billing: Downloading the generated asset costs $0. All financial billing occurs once upon job rendering completion.

Path Parameters

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";
import * as fs from "node:fs";

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

const jobId = "nrouter_video_01j89azxckm3287";

// Download binary video stream
const response = await client.videos.download(jobId);
const buffer = Buffer.from(await response.arrayBuffer());

await fs.promises.writeFile("rendered_video.mp4", buffer);
console.log("Video saved to rendered_video.mp4");

Error Handling & Status Codes

{
  "error": {
    "type": "gateway_error",
    "message": "Video rendering is still in progress. Current status: processing.",
    "code": "invalid_request"
  }
}

Binary Asset Streaming & Storage Architecture

When downloading high-definition video assets through GET /v1/videos/{id}/content, the response streams binary MP4 bytes directly from regional storage nodes.

Chunked Transfer & Range Requests

Large video files can exceed 50 MB depending on prompt length and duration. The nRouter gateway supports standard HTTP Range requests (bytes=start-end) for resuming interrupted downloads and seeking playback:

• Content-Type: Always set to video/mp4.
• Accept-Ranges: Emits bytes to signal partial content capability.
• Cache-Control: Completed video assets are immutable. Responses include public, max-age=31536000, immutable headers for optimal CDN edge caching.
• Content-Length: Provides exact byte count for progress bar calculations in client user interfaces.

Integration Patterns for Media Pipelines

1. Direct Cloud Storage Ingestion: Stream binary chunks directly to Amazon S3, Google Cloud Storage, or Azure Blob Storage without buffering the entire file into local application memory.
2. CDN Distribution: Store the binary asset in your public CDN bucket (e.g. Cloudflare R2, CloudFront) to serve end users with sub-millisecond first-frame delivery.
3. Automated Post-Processing: Pipe bytes into FFmpeg or transcoding workers to generate thumbnails, GIF previews, or HLS adaptive bitrate streams.

Storage Retention & Access Lifecycle Policies

Media artifacts generated through the nRouter video engine adhere to tenant-configurable retention policies:

• Default TTL: Video binary blobs remain available for download for 24 hours post-completion before automatic purge.
• Permanent Mirroring: Organizations requiring persistent archiving can configure automated cloud sync in their dashboard settings to mirror completed videos directly to enterprise S3 buckets.
• Signed URL Delegation: For secure browser-side rendering, backend servers can retrieve pre-signed temporary URLs with configurable expiry windows (15 minutes to 4 hours).
• Encryption at Rest: All stored video binaries are encrypted using AES-256 with tenant-isolated encryption keys, ensuring full compliance with SOC2 Type II and HIPAA requirements.

curl -X GET "https://example.com/v1/videos/string/content"

"video/mp4 byte stream"