Skip to main content

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.
For authenticated API-key requests, you can opt in to a paid input safety preflight by sending the moderation header. See Inline Moderation for supported video routes, inspectable image inputs, billing behavior, and error codes.

API Authentication

Supported authentication methods:
  1. API Key header: x-api-key: <your-api-key>
  2. Bearer token: Authorization: Bearer <your-api-key>
  3. 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 either imageDataUrl (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

Prefer videoUrl (camelCase) for source videos. Only send video if 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 via imageDataUrl or a public URL via imageUrl.

Seedance Models

Accepts base64 via imageDataUrl or a public URL via imageUrl. Ensure URLs are directly fetchable.

Supported Models

Use GET 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 through POST /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 (format vid_...)
  • id: Alias for runId (same value)
  • status: Always “pending” for initial response
  • model: The model used for generation
  • cost: Estimated/pre-charged cost
  • paymentSource: “USD” or “XNO”
  • remainingBalance: Account balance after deduction
  • prechargeLabel: Billing label for the precharge

Cost Information

Both the initial generation response and the status response include cost:
  • Initial response: estimated/pre-charged cost
  • Status response: final cost (when status is COMPLETED)
Pricing structures vary by model:
  • 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 a callback_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 a runId, poll the status endpoint until completion.

Status Endpoint

You can send requestId or runId; no model parameter is required.

Polling Example

Status Response States

In Progress

Completed

Failed

Status Values

  • IN_QUEUE: Request is queued
  • IN_PROGRESS: Video is being generated
  • COMPLETED: Video ready for download
  • FAILED: Generation failed
  • CANCELED: 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 either imageDataUrl (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

Use the same polling loop from Example 1 to monitor either request.

Example 3: Image-to-Video with JavaScript

Using a public image URL directly

Example 4: Image-to-Video with Python

Reuse the polling helper from the JavaScript example (or your own status loop) to watch these run IDs until completion.

Example 5: Batch Processing

Error Handling

Error Response Format

Error Types: 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 resolution
  • hunyuan-video: Pro mode available
  • Various Kling models: Pro variants

Audio Generation

  • veo3-video: Set generateAudio: true to include audio

Reference-to-Video

Supported by kling-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

  1. Choose the Right Model
    • Use text-to-video for creative generation
    • Use image-to-video for animating existing content
    • Consider cost vs quality tradeoffs
  2. Optimize Prompts
    • Be specific and descriptive
    • Include motion and camera directions
    • Avoid content policy violations
  3. Handle Async Operations
    • Implement proper polling with delays
    • Set reasonable timeouts (5-10 minutes)
    • Show progress to users
  4. Error Recovery
    • Implement retry logic for transient failures
    • Handle rate limits with exponential backoff
    • Provide clear error messages to users
  5. Cost Management
    • Check balance before submitting
    • Estimate costs before generation
    • Use shorter durations for testing