Skip to main content
POST
cURL
Image-conditioned models accept either imageDataUrl (base64) or a public imageUrl. The service uses the explicit value you provide before checking any saved attachments.

Overview

POST /generate-video submits an asynchronous job to create, extend, or edit a video. The endpoint responds immediately with runId, id, model, and status: "pending". runId and id are the same NanoGPT job identifier (format vid_...). Poll the unified Video Status endpoint with that job ID until you receive final assets. Duration-based billing is assessed after completion.
Zero Data Retention (ZDR) does not cover video generation or 3D requests through this 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.
Errors include descriptive JSON payloads. Surface the error.message (and HTTP status) to help users correct content-policy or validation issues.

Extend Workflows

Use POST /api/generate-video with an extend model plus prompt and a source video (videoUrl, videoDataUrl, or videoAttachmentId). video is only accepted by select models (for example, wan-wavespeed-25-extend). Max source video length: 120 seconds.

Request Schema

Only include the fields required by your chosen model. Unknown keys are ignored, but some models fail when extra media fields are present.

Core Fields

Media Inputs

Provide only the media fields that your target model expects. Extra media inputs often trigger validation errors. Prefer videoUrl (camelCase) for source videos; only send video when the model explicitly requires it.

Advanced Controls

Model Discovery

Video model IDs and supported fields change over time. Use GET /api/v1/models?detailed=true to discover the current list and select a model intended for video generation. Notes:
  • Different models accept different media inputs (for example imageUrl vs a source videoUrl) and may support different duration / resolution options.
  • If you see validation errors, first retry with only the minimal required fields for your chosen model.

Returned seeds

For these models NanoGPT picks the seed of a random request itself, sends it to the provider and returns it, so you can reuse it. Random seeds are drawn from 0 to 2147483647.
  • Wan 2.2, 2.5, 2.6, 2.7 and 3.0 video models, including Spicy, edit, extend and speech-to-video variants, and HappyHorse 1.0 and 1.1
  • Veo 3.1 and Veo 3.1 Fast, including Extend
  • Seedance 1.0 Pro, 1.0 Pro Fast, 1.5 Pro and 1.5 Pro Fast (including Extend), and the Seedance 2.0, 2.0 Fast, 2.0 Mini and 2.5 Spicy image-to-video models
  • P-Video 2 and P-Video 2 Pro
  • PixVerse V6 Max: 0 also means random, so random seeds start at 1
  • HeyGen Video 1: explicit seeds up to 4294967295 are accepted
  • LTX-2.3 Spicy and MiniMax H3 Spicy image-to-video

Async Processing & Status Polling

  • The submission response includes { runId, id, model, status: "pending" } where id and runId are identical.
  • Submissions to models with returned seeds also return seed: the seed NanoGPT sent to the provider, including one it picked for a random request. Send it back as seed to reuse it; identical output is not guaranteed.
  • Poll /api/video/status?requestId=<runId> (or runId) until the job reaches status: "COMPLETED" or status: "FAILED". The legacy /api/generate-video/status endpoint is deprecated.
  • Many jobs emit intermediate states (queued, processing, generating, delivering). Persist them if you need audit trails.
  • Failed jobs include an error object. Surface the message and adjust prompts or inputs before retrying.
  • Duration and resolution determine credit usage.

Response example

Content & Safety Notes

Some models may block prompts that violate content policies. Non-200 responses describe the violation reason; relay these messages verbatim to users or implement automated prompt adjustments.

Next Steps

  • Poll the Video Status endpoint after every submission to retrieve final assets.
  • Keep customer-facing pricing tables in sync with the API behavior you observe in production.

Authorizations

x-api-key
string
header
required

Body

application/json

Parameters for video generation across different models and providers

model
string
required

The video model to use for generation. See the docs for the current model list and required inputs.

callback_url
string<uri>

Public HTTPS URL that receives a signed webhook when the job reaches a final status. Delivery can fail or repeat, so keep polling as a fallback. Needs an API key and a webhook signing secret, generated in Settings. See the Webhooks page.

Maximum string length: 2048
prompt
string

Text prompt describing the video to generate

Example:

"A serene lake at sunset with gentle ripples on the water"

script
string

Fully-written script for LongStories models (takes precedence over prompt)

conversationUUID
string

UUID for conversation tracking

projectId
string

Project identifier for LongStories models

framework
enum<string>
default:default

Story framework for LongStories models

Available options:
default,
emotional_story,
product_showcase,
tutorial
shortRequestEnhancer
boolean
default:false

Smart Enhancement: if true, automatically choose better framework and add Director Notes if necessary

targetLengthInWords
integer
default:70

Target length in words for LongStories models (legacy parameter)

targetLengthInSeconds
integer

Target length in seconds (alternative to words)

directorNotes
string

Prompt for the image generation engine (LongStories). Example: 'Warm lighting' or 'Make the first image very impactful'

Example:

"Warm, cozy lighting with focus on people interacting"

aspectRatio
enum<string>
default:9:16

Video aspect ratio for LongStories

Available options:
9:16,
16:9
scriptConfig
object

Script generation configuration for LongStories

imageConfig
object

Image generation configuration for LongStories

videoConfig
object

Video generation configuration for LongStories

voiceoverConfig
object

Voiceover configuration for LongStories

captionsConfig
object

Captions configuration for LongStories

effectsConfig
object

Effects configuration for LongStories

musicConfig
object

Music configuration for LongStories

voice
string

Legacy: Voice ID for narration (use voiceoverConfig.voiceId instead)

Example:

"pNInz6obpgDQGcFmaJgB"

captionsShow
boolean
default:true

Legacy: Whether to show captions (use captionsConfig.captionsEnabled instead)

captionsStyle
enum<string>
default:default

Legacy: Style for captions (use captionsConfig.captionsStyle instead)

Available options:
default,
minimal,
neon,
cinematic,
fancy,
tiktok,
highlight,
gradient,
instagram,
vida,
manuscripts
effects
object

Legacy: Video effects configuration (use effectsConfig instead)

quality
enum<string>
default:medium

Legacy: Video quality (handled by videoConfig now)

Available options:
low,
medium,
high
motion
object

Legacy: Motion configuration (handled by videoConfig now)

music
string

Legacy: Music track (use musicConfig instead)

Example:

"video-creation/music/dramatic_cinematic_score.mp3"

duration

Video duration (format varies by model - '5s' for Veo2, '5' for Kling, etc.)

Example:

"5s"

aspect_ratio
enum<string>
default:16:9

Aspect ratio (supported by select models)

Available options:
16:9,
9:16,
1:1,
4:3,
3:4
negative_prompt
string

Negative prompt to avoid certain elements

Example:

"blur, distort, and low quality"

cfg_scale
number
default:0.5

Classifier-free guidance scale

Required range: 0 <= x <= 20
imageDataUrl
string

Base64 data URL of input image for image-to-video models. Aliases image_data_url and image are also accepted and normalized.

Example:

"data:image/jpeg;base64,/9j/4AAQ..."

imageUrl
string

Public HTTPS URL of the input image (interchangeable with imageDataUrl). The service will prioritize whichever field you supply before falling back to library attachments.

Example:

"https://images.unsplash.com/photo-1504196606672-aef5c9cefc92?w=1024"

imageAttachmentId
string

Library attachment ID for input image

videoUrl
string

Public HTTPS URL of the input video (extend/edit/upscale). Preferred field name for source videos.

videoDataUrl
string

Base64 data URL of the input video.

video
string

Alternate video field accepted by select providers.

videoAttachmentId
string

Library attachment ID for input video.

prompt_optimizer
boolean
default:true

Whether to optimize the prompt (MiniMax model)

num_inference_steps
integer
default:30

Number of inference steps

Required range: 1 <= x <= 50
pro_mode
boolean
default:false

Enable pro mode for Hunyuan Video

resolution
enum<string>
default:720p

Video resolution

Available options:
720p,
1080p,
540p
num_frames
default:81

Number of frames to generate

frames_per_second
integer
default:16

Frames per second

Required range: 5 <= x <= 24
seed
integer

Optional seed forwarded on model/provider routes that support it. For models with returned seeds (see the video generation guide), omit it, leave it blank or send -1 for a random seed: NanoGPT picks one, sends it to the provider and returns it as seed. This may improve reproducibility but does not guarantee identical output.

enable_safety_checker
boolean
default:true

Enable safety content filtering

showExplicitContent
boolean
default:false

Allow explicit content (inverse of safety checker)

enable_prompt_expansion
boolean

Enable automatic prompt expansion

acceleration
boolean

Enable acceleration for faster processing

shift
number

Shift parameter for certain models

age_slider
integer
default:18

Age setting for PromptChan model

Required range: 18 <= x <= 60
audioEnabled
boolean
default:false

Enable audio for PromptChan model

video_quality
enum<string>
default:Standard

Video quality for PromptChan model

Available options:
Standard,
High
aspect
enum<string>
default:Portrait

Aspect setting for PromptChan model

Available options:
Portrait,
Landscape,
Square

Response

Video generation request submitted successfully (asynchronous processing)

runId
string
required

Unique identifier for the video generation request

status
enum<string>
default:pending
required

Current status of the generation

Available options:
pending,
processing,
completed,
failed
model
string
required

The model used for generation

projectId
string

Project identifier (for LongStories models)

seed
integer

The seed NanoGPT sent to the provider, returned for models with returned seeds. Send it back as seed to request the same seed again; identical output is not guaranteed.

cost
number

Cost of the video generation

paymentSource
string

Payment source used (USD or XNO)

remainingBalance
number

Remaining balance after the generation

prechargeLabel
string

Provider label for the precharge