Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
CLI First

# List active jobs
naive jobs --status processing --limit 10

# Get one job
naive jobs get <job-id>

# Cancel a running job
naive jobs cancel <job-id>

​
The Jobs System

All image/video generation operations and deep research go through a unified jobs system. The pattern is always:
  1. Submit → get job_id (202 response)
  2. Poll → check status via GET /v1/jobs/:id
  3. Complete → job finishes, credits charged, result available

​
Job Statuses

StatusMeaning
queuedSubmitted, waiting to start
processingRunning (may include progress %)
completedDone — result available, credits charged
failedError — no credits charged
cancelledCancelled by user — no credits charged

​
Listing Jobs

GET /v1/jobs?status=processing&limit=10
Filter by status: queued, processing, completed, failed, cancelled.

​
Getting Job Details

GET /v1/jobs/:id

{
  "id": "job-uuid",
  "type": "video_generation",
  "status": "completed",
  "progress": 100,
  "model": "fal-ai/kling-video/v3/pro/text-to-video",
  "result": { "..." },
  "error": null,
  "credits_used": 5,
  "fal_request_id": "fal-req-123",
  "created_at": "2026-05-02T10:30:00Z",
  "started_at": "2026-05-02T10:30:01Z",
  "completed_at": "2026-05-02T10:31:02Z",
  "metadata": { "estimated_seconds": 60 }
}

​
Cancelling a Job

DELETE /v1/jobs/:id
Only works for jobs in queued or processing state.

​
Job Types

TypeCreated By
image_generationPOST /v1/images/generate
video_generationPOST /v1/video/generate
deep_researchPOST /v1/search/research (thorough/exhaustive)

​
Convenience Aliases

Each primitive has its own status endpoint that filters to its job type:
  • GET /v1/images/:jobId — same as /v1/jobs/:id but validates it’s an image job
  • GET /v1/video/:jobId — same as /v1/jobs/:id but validates it’s a video job