Overview
The NanoGPT API provides advanced video generation capabilities using state-of-the-art models. This guide covers how to use our video generation endpoints.Zero Data Retention (ZDR) does not cover video generation or 3D requests through the video endpoint. These requests still run when ZDR-only routing is enabled, and providers may store your prompts, input media and outputs. See the Privacy Policy.
moderation header. See Inline Moderation for supported video routes, inspectable image inputs, billing behavior, and error codes.
API Authentication
Supported authentication methods:- API Key header:
x-api-key: <your-api-key> - Bearer token:
Authorization: Bearer <your-api-key> - Cookie session: for web clients (automatic)
Header Examples
Making a Video Generation Request
Endpoint
Request Headers
Request Body
Basic Text-to-Video Request
Image-to-Video Request
Image-conditioned models accept eitherimageDataUrl (base64) or imageUrl (a public HTTPS link). The platform always uses the explicit field you send before falling back to any library attachments.
Uploads sent via the API must be 4 MB or smaller. For larger assets, host them externally and provide an imageUrl.
Base64 input
Public URL input
Additional Request Parameters
These parameters are available across models. Only send the fields your chosen model supports.Core Parameters
PrefervideoUrl(camelCase) for source videos. Only sendvideoif the model explicitly requires it.
Audio Parameters (lipsync/avatar models)
Model-Specific Parameters
Model-Specific Parameters
Veo Models
Kling Models
Hunyuan Models
Wan Image-to-Video
Accepts base64 viaimageDataUrlor a public URL viaimageUrl.
Seedance Models
Accepts base64 viaimageDataUrlor a public URL viaimageUrl. Ensure URLs are directly fetchable.
Supported Models
UseGET https://api.nano-gpt.com/api/v1/video-models for the current catalog, supported parameters, and pricing. capabilities.audio_generation means the model can create a soundtrack; capabilities.audio_input means it accepts uploaded audio. These are separate capabilities.
Gemini Omni Flash (google/gemini-omni-flash), 1.1 (google/gemini-omni-flash/v1.1), and 1.2 (google/gemini-omni-flash/v1.2) generate native audio with video. Gemini Omni 1.2 does not accept audio uploads. Its separate /upscale model preserves existing audio rather than generating a new soundtrack.
Gemini Omni 1.2 generation reserves $15, then refunds unused funds before delivery. The final charge uses input, text/thinking output, and video output tokens; $15 is a refundable ceiling, not a fixed per-video price. Native audio has no separate fee. Read the model’s pricing metadata for current token rates.
Text-to-Video Models
Image-to-Video Only Models
Avatar/Lipsync Models
Utility Models
Extension Models
Extend models run throughPOST /api/generate-video with prompt plus a source video input (videoUrl, videoDataUrl, or videoAttachmentId).
Max source video length: 120 seconds.
Seedance 1.5 Pro Extend (
bytedance-seedance-v1.5-pro-extend) has retired. New requests return HTTP 410 with model_unavailable; NanoGPT does not automatically substitute another model. Choose an available extension model from the live video model catalog.
Longstories Models (Scripted Video)
Response Format
Initial Response (202 Accepted)
Response Fields
runId: NanoGPT job ID used for polling (formatvid_...)id: Alias forrunId(same value)status: Always “pending” for initial responsemodel: The model used for generationcost: Estimated/pre-charged costpaymentSource: “USD” or “XNO”remainingBalance: Account balance after deductionprechargeLabel: Billing label for the precharge
Cost Information
Both the initial generation response and the status response includecost:
- Initial response: estimated/pre-charged cost
- Status response: final cost (when
statusisCOMPLETED)
- Fixed: flat rate per generation
- Per-Second: rate x duration
- Resolution-Based: rates per resolution tier
- Duration-Based: step pricing (5s vs 10s)
- Mode-Based: different rates for T2V vs I2V
Getting Notified When a Job Finishes
API-key requests can send acallback_url to get a signed notification when the job reaches a final status. Delivery can fail or repeat, so keep polling as a fallback. See Webhooks.
Polling for Status
After receiving arunId, poll the status endpoint until completion.
Status Endpoint
requestId or runId; no model parameter is required.
Polling Example
Status Response States
In Progress
Completed
Failed
Status Values
IN_QUEUE: Request is queuedIN_PROGRESS: Video is being generatedCOMPLETED: Video ready for downloadFAILED: Generation failedCANCELED: Request was canceled
Additional Endpoints
GET /api/generate-video/recover
Recover recent video generation runs for a user.
Query Parameters
Rate Limit: 20 requests/minute
GET /api/generate-video/content
Serves a video NanoGPT stores. Status responses read by the creating account (or for an x402 job, or through a statusUrl) return these URLs signed (expires, sig): they work without an API key for 24 hours. After that, poll the status endpoint again for a fresh one, or fetch the URL with the creating account’s API key or session.
Query Parameters
Complete Examples
The submit + poll flow works the same regardless of how you supply the image: image-conditioned models accept eitherimageDataUrl (base64) or a public imageUrl, and the platform prefers whichever field you send before checking library attachments.
Example 1: Text-to-Video with cURL
Example 2: Image-to-Video with cURL
Base64 input
Public URL input
Example 3: Image-to-Video with JavaScript
Using a public image URL directly
Example 4: Image-to-Video with Python
Example 5: Batch Processing
Error Handling
Error Response Format
CONTENT_POLICY_VIOLATION, PRO_REQUIRED, INSUFFICIENT_BALANCE, RATE_LIMITED
Error Handling Best Practices
Rate Limits
Additional Notes
Pro Mode
sora-2: Pro mode required for 1792x1024 resolutionhunyuan-video: Pro mode available- Various Kling models: Pro variants
Audio Generation
veo3-video: SetgenerateAudio: trueto include audio
Reference-to-Video
Supported bykling-video-o1, kling-video-o1-standard, wan-wavespeed-26.
Use referenceImages with image URLs or data URLs.
Automatic Refunds
Refunds are automatically issued when:- The job returns a failure
- Content policy violation (before processing)
- Submission fails before acknowledgement
Best Practices
-
Choose the Right Model
- Use text-to-video for creative generation
- Use image-to-video for animating existing content
- Consider cost vs quality tradeoffs
-
Optimize Prompts
- Be specific and descriptive
- Include motion and camera directions
- Avoid content policy violations
-
Handle Async Operations
- Implement proper polling with delays
- Set reasonable timeouts (5-10 minutes)
- Show progress to users
-
Error Recovery
- Implement retry logic for transient failures
- Handle rate limits with exponential backoff
- Provide clear error messages to users
-
Cost Management
- Check balance before submitting
- Estimate costs before generation
- Use shorter durations for testing