Video Generation

POST /api/v1/video starts a video generation job for the active business attached to your API key. GET /api/v1/video lists generated video jobs and returns monthly video credit usage based on persisted generation history. Use an API key with content:write to create video jobs and content:read to list them. Video generation is available on plans with monthly video credits.

X-NearIQ-Key

string

required

Your API key from Settings > API Keys.

POST /api/v1/video

Request body

Name	Type	Required	Default	Notes
`prompt`	string	yes	-	Video concept, 5-500 characters.
`duration`	enum	no	`15`	`5`, `15`, or `30` seconds. Credits: 1, 2, or 4.
`aspectRatio`	enum	no	`16:9`	`16:9`, `9:16`, or `1:1`.

curl https://app.neariq.io/api/v1/video \
  -X POST \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Membership promo showing coaching, equipment, and happy members",
    "duration": "15",
    "aspectRatio": "9:16"
  }'

Response

{
  "id": "vg_...",
  "status": "processing",
  "prompt": "Membership promo showing coaching, equipment, and happy members",
  "duration": "15",
  "aspectRatio": "9:16",
  "creditsUsed": 2,
  "monthlyUsage": {
    "used": 6,
    "limit": 12
  },
  "_receipt": {
    "requestId": "req_...",
    "generatedAt": "2026-06-09T16:20:00.000Z"
  }
}

The id is opaque. Use the app-session status/download endpoint only from an authenticated dashboard session; public API keys should treat the v1 create response and GET /api/v1/video list as the supported contract.

GET /api/v1/video

Lists generated video jobs for the active business.

Query	Type	Default	Notes
`limit`	integer	`20`	Max `50`.
`status`	enum	`all`	`completed`, `processing`, `failed`, or `all`.

curl "https://app.neariq.io/api/v1/video?limit=20&status=all" \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "videos": [
    {
      "id": "vg_...",
      "prompt": "Membership promo showing coaching, equipment, and happy members",
      "status": "processing",
      "videoUrl": null,
      "thumbnailUrl": null,
      "durationSeconds": 15,
      "creditsUsed": 2,
      "captions": [],
      "createdAt": "2026-06-09T16:20:00.000Z",
      "completedAt": null
    }
  ],
  "total": 1,
  "monthlyUsage": {
    "used": 6,
    "limit": 12
  }
}

Monthly usage sums creditsUsed for completed and processing jobs in the current calendar month. Failed jobs are not counted.

Dashboard Session Endpoints

The NearIQ dashboard uses authenticated app-session routes for richer Content Studio workflows:

POST /api/businesses/me/video creates a commercial source bundle with script, audio configuration, source-shot metadata, and compositing guidance.
GET /api/businesses/me/video checks status or downloads a generated source when the signed app session is allowed to do so.
POST /api/businesses/me/video/captions creates timed caption/subtitle cues for a generated video, stores them in video_generations.captions, and returns a captionCues array plus a composite-ready burn-in body.
POST /api/businesses/me/video/composite-clips stitches selected generated clips from the active business into one final MP4 with hard-cut or fade transitions.
POST /api/businesses/me/video/composite creates the final commercial output from a generated source bundle, adds allowed voice/music/text overlays, normalizes duration, and applies plan watermark rules.
GET /api/businesses/me/video/composite polls a composite job until completion.

These app-session routes require a signed NearIQ dashboard session and are not a replacement for the public v1 API key contract. Dashboard video jobs return video.script and the selected audio configuration so the client can keep audioConfig.speechPace, audioConfig.pitch, audioConfig.voiceVolume, audioConfig.musicVolume, audioConfig.nativeVolume, audioConfig.voiceStartSec, and audioConfig.musicStartSec attached to the source bundle. Final rendering uses a short-lived signed source-video URL and the charge_only_on_composite_output policy: NearIQ deducts 1 additional video credit only when a configured compositor returns a completed output. POST /api/businesses/me/video/captions accepts { "videoId": "...", "script": "optional script", "captionStyle": "clean", "burnIn": true }. The route returns captionCues shaped as { startSec, endSec, text }[], persists them on video_generations.captions, and includes compositeBody with the same captionCues for /api/businesses/me/video/composite. Caption generation costs 1 video credit when new cues are generated. Reusing saved captions does not charge again. POST /api/businesses/me/video/composite-clips accepts

{ "clipIds": ["..."], "transition": { "type": "cut" | "fade", "durationSec": 0.5 }, "style": "promo", "duration": "15", "aspect": "16:9" }

. The route verifies that every clipIds entry belongs to the active business and is completed, expands saved source bundles, signs each source segment for the compositor, and returns either a completed composite.url or a processing response with jobToken and statusEndpoint: "/api/businesses/me/video/composite". Multi-clip stitching costs 1 additional video credit only when the compositor returns a completed output. The compositor worker exposes /compose for render jobs and serves completed files from /composites/. Configure the compositor endpoint and shared signing secret through your deployment secret manager. In production, verify premium narration is available before charging, and confirm the final duration matches the requested slot within the compositor tolerance.

Errors

Status	Meaning
`400`	Invalid prompt, duration, aspect ratio, or missing active business.
`403`	Plan, API-key scope, or team permission does not allow video generation.
`429`	Monthly video credit limit would be exceeded by the requested duration.
`503`	Video generation is not configured for the current environment.

Organization members also need the create_video permission when the active business belongs to a team workspace.

​POST /api/v1/video

​Request body

​Response

​GET /api/v1/video

​Dashboard Session Endpoints