Videos
Initiate asynchronous video generation jobs from descriptive text prompts across supported provider models with sealed job handles and lifecycle polling.
The /v1/videos endpoint initiates asynchronous video generation jobs from text prompts across models like Google Veo and OpenAI Sora. Requests return an immediate job ID for status polling via GET /v1/videos/{id} and binary retrieval via GET /v1/videos/{id}/content.
POST https://api.nrouter.ai/v1/videosRequests run preflight as Chat Completions: key validation, rate limits, and content inspection (x-nr-guardrails: blocked returns HTTP 400 with zero hold). Duration and resolution credit holds settle upon generation completion.
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | Model ID (e.g. veo-2.0, sora-1.0). |
prompt | string | Yes | — | Text description of scene, lighting, action, and camera movement. |
seconds | integer | No | 5 | Target video duration in seconds (typically 5 to 10). |
size | string | No | 1280x720 | Output resolution (e.g. 1280x720, 1920x1080, 720x1280). |
fps | integer | No | 24 | Render frame rate (24 or 30). |
Response
{
"id": "nrouter_video_01j89azxckm3287",
"object": "video.generation",
"status": "queued",
"created": 1709251200,
"model": "veo-2.0"
}Examples
curl -X POST https://api.nrouter.ai/v1/videos \
-H "Authorization: Bearer $NROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-2.0","prompt":"Drone shot over pine forest.","seconds":5}'Headers & Errors
Required request headers: Authorization: Bearer sk-nrouter-... and Content-Type: application/json. Response telemetry includes x-nr-request-id, x-nr-latency-ms, x-nr-request-cost, x-nr-model. See Chat Completions.
| HTTP Status | Error Code | Reason |
|---|---|---|
| 400 Bad Request | invalid_request | Missing model/prompt, or invalid duration/resolution. |
| 400 Bad Request | guardrail_blocked | Prompt violated safety policies or injection filters. |
| 401 Unauthorized | invalid_api_key | Virtual key missing, expired, or invalid. |
| 402 Payment Required | insufficient_credits | Organization balance insufficient for duration hold. |
| 404 Not Found | model_not_found | Video model unrecognized or unauthorized. |
| 429 Too Many Requests | rate_limit_exceeded | Concurrent generation limit exceeded; check x-nr-limit-source. |
Authorization
NRouterApiKey Your nRouter virtual key (sk-nrouter-…). Sent as Authorization: Bearer sk-nrouter-….
In: header
Header Parameters
Target MCP server ID when routing MCP tool calls or prompts through the gateway
Caller SDK runtime language identification (e.g. typescript, python, rust, go)
Caller session identifier allowed at edge for grouping related client turns
Inbound trace detail level override for request lifecycle spans
Value in
- "off"
- "stages"
- "verbose"
Inbound stage-level trace emission override
Value in
- "off"
- "stages"
- "verbose"
Accepted so a client sending it is not refused; the value is not recorded and not propagated. Every response carries the gateway's own trace ID in this header, never the one sent.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
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"}