Video Generation

Video is the creation primitive for moving content. Naive exposes video generation models behind a consistent async interface — text-to-video for scripted content and image-to-video for animating stills. All jobs go through the unified jobs system with credits billed on completion.

CLI First

# Generate video and wait for completion
naive video generate --model fal-ai/kling-video/v3/pro/text-to-video "A golden retriever running on a beach at sunset" --duration 5 --aspect-ratio 16:9 --wait

# See available models
naive video models

Tools

Tool	Type	Description	Cost
`generate_video`	Core	Generate video from text or image (async)	Dynamic (model/duration-dependent)
`video_models`	Core	List all available video generation models	Free
`video_status`	Core	Check status of a video generation job	Free

Generating Video

The generate_video tool submits an async video generation job. A model is required — there is no default. The input object supports all model-specific parameters.

curl -X POST https://api.usenaive.ai/v1/video/generate \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fal-ai/kling-video/v3/pro/text-to-video",
    "input": {
      "prompt": "A golden retriever running on a beach at sunset, cinematic slow motion",
      "duration": "5",
      "aspect_ratio": "16:9"
    }
  }'

Response (202):

{
  "job_id": "job-uuid",
  "status": "queued",
  "type": "video_generation",
  "model": "fal-ai/kling-video/v3/pro/text-to-video",
  "estimated_seconds": 60,
  "estimated_credits": 3.5,
  "hint": "Poll GET /v1/jobs/job-uuid or GET /v1/video/job-uuid. Credits charged on completion only."
}

Parameters

Param	Type	Required	Default	Description
`prompt`	string	Yes	—	Text description of the video
`duration`	string	No	`"5"`	Video length: `"5"` or `"10"` seconds (Kling models)
`aspect_ratio`	string	No	`"16:9"`	Output ratio: `"16:9"`, `"9:16"`, `"1:1"`
`image_url`	string	No	—	Source image for image-to-video models
`cfg_scale`	number	No	0.5	Guidance strength 0–1 (higher = more literal)
`negative_prompt`	string	No	—	What to avoid in the video
`generate_audio`	boolean	No	true	Enable native audio (Kling v3 only)

Polling for Completion

Video generation takes 30-120 seconds. Poll the job:

curl https://api.usenaive.ai/v1/video/job-uuid \
  -H "Authorization: Bearer nv_sk_your_key"

Response (completed):

{
  "status": "completed",
  "result": {
    "video": {
      "url": "https://fal.media/files/.../video.mp4",
      "content_type": "video/mp4",
      "file_size": 4521987
    }
  },
  "credits_used": 3.5
}

Poll every 15-30 seconds. The progress field (0-100) shows generation percentage when available.

Cost

Video pricing is dynamic — based on the model’s per-second cost, converted to credits at $0.50/credit. Preview costs:

curl "https://api.usenaive.ai/v1/video/pricing?model=fal-ai/kling-video/v3/pro/text-to-video&duration=5" \
  -H "Authorization: Bearer nv_sk_your_key"

{
  "model": "fal-ai/kling-video/v3/pro/text-to-video",
  "duration": 5,
  "estimated_credits": 3.5,
  "fal_unit_price_usd": 0.07,
  "credit_value_usd": 0.50
}

Available Models

Use GET /v1/video/models for the full dynamically-fetched list. Common models:

Model	Mode	Best For
`fal-ai/kling-video/v3/pro/text-to-video`	text-to-video	Highest quality, native audio
`fal-ai/kling-video/v3/pro/image-to-video`	image-to-video	Animate still images
`fal-ai/kling-video/v3/standard/text-to-video`	text-to-video	Good quality, faster
`fal-ai/minimax-video/video-01-live`	text-to-video	Fast generation
`fal-ai/wan/v2.7/text-to-video`	text-to-video	High resolution options

Text-to-Video vs Image-to-Video

Text-to-Video
Image-to-Video

Generate entirely from a text prompt:

{
  "model": "fal-ai/kling-video/v3/pro/text-to-video",
  "input": {
    "prompt": "A timelapse of a flower blooming in a garden",
    "duration": "5",
    "aspect_ratio": "16:9"
  }
}

Best for: product demos, abstract animations, scripted content.

Animate a still image with optional prompt guidance:

{
  "model": "fal-ai/kling-video/v3/pro/image-to-video",
  "input": {
    "image_url": "https://example.com/product-photo.jpg",
    "prompt": "Slow zoom in with gentle parallax effect",
    "duration": "5"
  }
}

Best for: product shots, hero images, adding motion to existing assets.

Error Handling

Error	Cause	Recovery
`insufficient_credits`	Not enough credits for generation	Preview cost with `/v1/video/pricing`, then top up
`provider_error`	AI model provider rejected the request	Check model parameters against `/v1/video/models`
`invalid_model`	Model ID not recognized	Use `GET /v1/video/models` for valid IDs

Typical Workflow

Agent receives task: "Create a product demo video"
    │
    ├─ GET /v1/video/models                    → List available models
    │   → 8 models available
    │
    ├─ GET /v1/video/pricing?model=...&dur=5   → Preview cost
    │   → estimated_credits: 3.5
    │
    ├─ POST /v1/video/generate                 → Submit generation job
    │   { model: "fal-ai/kling-video/v3/pro/text-to-video",
    │     input: { prompt: "Product showcase...", duration: "5" } }
    │   → job_id: job-uuid
    │
    ├─ GET /v1/video/job-uuid                  → Poll every 15-30s
    │   → status: processing, progress: 65%
    │
    ├─ GET /v1/video/job-uuid                  → Poll again
    │   → status: completed, video URL ready
    │
    └─ POST /v1/email/send                     → Share with team
        { body: "Video ready: https://fal.media/..." }

Getting Started

Primitives

CLI First

Tools

Generating Video

Parameters

Polling for Completion

Cost

Available Models

Text-to-Video vs Image-to-Video

Error Handling

Typical Workflow

Getting Started

Primitives

Documentation Index

​CLI First

​Tools

​Generating Video

​Parameters

​Polling for Completion

​Cost

​Available Models

​Text-to-Video vs Image-to-Video

​Error Handling

​Typical Workflow

CLI First

Tools

Generating Video

Parameters

Polling for Completion

Cost

Available Models

Text-to-Video vs Image-to-Video

Error Handling

Typical Workflow