AI Narration

A Narration artifact (txt_…) is produced by a root ai_narration job from a source video — no transcription is required. The record includes timed script segments and a presigned URL for the narrated output video.

Create a job with POST /v1/jobs (serviceType: ai_narration, sourceType: s3_direct or s3_presigned). Poll until status: completed, then use resultSummary.textSourceId from GET /v1/jobs/:jobId to retrieve the narration id, then fetch the full artifact below.

Downstream services (translation, clips, thumbnails, metadata, summarization, indexer) accept input.textSourceId when referencing a completed text source.

Retrieve a narrationGET/v1/narrations/{narrationId}chevron_right
List narrationsGET/v1/narrationschevron_right

The Narration object

textSourceIdstring: Text source identifier (txt_…).
jobIdstring: Parent ai_narration job (job_…).
segmentsarray: Timed narration script segments (id, start, end, text).
textstring: Full script text (segments joined).
textPreviewstring: Truncated preview for lists.
segmentCountinteger: Number of narrated segments.
voicestring: TTS voice used for the output.
videoTypestring: Detected or user-selected video category.
outputVideoKeystring: S3 key of the narrated output video.
videoUrlstring: Presigned GET URL for the output video (detail view).

{
  "textSourceId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "text": "Scene one narration. Scene two narration.",
  "textPreview": "Scene one narration. Scene two narration.",
  "segmentCount": 2,
  "segments": [
    { "id": "s0", "start": 0, "end": 3, "text": "Scene one narration." },
    { "id": "s1", "start": 3, "end": 6, "text": "Scene two narration." }
  ],
  "voice": "nova",
  "videoType": "generic",
  "outputVideoKey": "ai-narration/job_01HZ.../output.mp4",
  "videoUrl": "https://...",
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
}

Retrieve a narration

GET/v1/narrations/{narrationId}

Returns one Narration by its narrationId.

Requires permission

narration:read

Parameters

narrationIdstring: Narration identifier (txt_…).

Returns

Returns a Narration object.

See the the narration object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/narrations/txt_02HX2K9V3JEK4WYZN6F0XQ2W8N" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "textSourceId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "text": "Scene one narration. Scene two narration.",
  "textPreview": "Scene one narration. Scene two narration.",
  "segmentCount": 2,
  "segments": [
    { "id": "s0", "start": 0, "end": 3, "text": "Scene one narration." },
    { "id": "s1", "start": 3, "end": 6, "text": "Scene two narration." }
  ],
  "voice": "nova",
  "videoType": "generic",
  "outputVideoKey": "ai-narration/job_01HZ.../output.mp4",
  "videoUrl": "https://...",
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

List narrations

GET/v1/narrations

Paginated list items with preview fields and job metadata — not full text or segments.

Requires permission

narration:list

List item fields: textSourceId, jobId, workspaceId, projectId, textPreview, segmentCount, voice, videoType, jobStatus, jobInput, jobCompletedAt, createdAt.

Query parameters

pageinteger, optional: Default 1.
limitinteger, optional: Default 20, max 100.

Returns

data array of list items (see example); metadata.pagination.

See the the narration object for attribute details.

curl -G "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/narrations" \
  -H "Authorization: Bearer sk_prj_..." \
-d "page=1" \
-d "limit=20"

{
  "data": [{
  "textSourceId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "displayName": "Product demo — narrated",
  "textPreview": "Scene one narration. Scene two narration.",
  "segmentCount": 2,
  "voice": "nova",
  "videoType": "generic",
  "outputVideoKey": "ai-narration/job_01HZ.../output.mp4",
  "jobStatus": "completed",
  "jobInput": {
    "sourceType": "s3_direct",
    "connectionId": "conn_abc123",
    "bucket": "my-videos",
    "sourceKey": "videos/my-video.mp4"
  },
  "jobCompletedAt": "2024-05-15T10:30:00.000Z",
  "createdAt": "2024-05-15T10:30:00.000Z"
}],
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1",
    "pagination": {
      "total": 3,
      "page": 1,
      "limit": 20,
      "totalPages": 1,
      "from": 1,
      "to": 3,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}