> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Generation

> Generate provider-neutral AI video jobs and track monthly video credit usage.

`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.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys.
</ParamField>

## 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`.                        |

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const video = await client.video.create({
    prompt: 'Membership promo showing coaching, equipment, and happy members',
    duration: '15',
    aspectRatio: '9:16',
  })
  ```

  ```python Python theme={null}
  video = client.create_video(
      prompt="Membership promo showing coaching, equipment, and happy members",
      duration="15",
      aspect_ratio="9:16",
  )
  ```
</RequestExample>

### Response

```json theme={null}
{
  "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`. |

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

```json theme={null}
{
  "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/talking-avatar` creates a talking-avatar render from a consented avatar image plus script/audio and writes a zero-credit processing ledger row.
* `GET /api/businesses/me/video/talking-avatar` polls talking-avatar status, charges video credits only when the provider returns a completed MP4, and proxies completed downloads for the signed app session.
* `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.

Final video composition runs behind NearIQ. Configure video composition through your deployment secret manager. In production, verify premium narration is available before charging, and confirm the final duration matches the requested slot.

## 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.