Thumbnails

When a thumbnail job completes, the platform stores thumbnail metadata on the linked Transcription (thumbnails subdocument). Image files are not stored on Perchat — the worker uploads JPEGs to your S3 bucket using a saved storage connection. API responses include bucket and key per item; use GET /v1/transcriptions/{id}?include=thumbnailUrls for short-lived download URLs on s3_direct jobs.

Each thumbnail job generates at most 3 JPEG variants. Set input.options.thumbnailCount to 1, 2, or 3 — values above 3 are rejected at validation. Outputs are written to your bucket via the job's storage connection.

Thumbnail jobs require a completed transcription with segments (input.transcriptionId). Pipeline tuning — vision model, frame limits, and imageQuality (low | medium | high | auto for gpt-image-1) — is platform-managed and snapshotted into job.input.options at create. The imageModel is set by plan (free → gpt-image-1, enterprise → gpt-image-2). Clients may set options.thumbnailCount (1–3), options.nonAiThumbnailCount, and the output size via options.ratioWidth / ratioHeight / resolution. Create jobs via POST /v1/jobs (serviceType: thumbnail). Poll the job until status: completed, then read metadata from the transcript or the convenience endpoints below.

Re-running accumulates. Running another thumbnail job for the same transcriptionId adds new, visually different thumbnails (different source frames and a fresh look) to the existing set — it does not replace them. So items[] / nonAiItems[] and their counts grow with each run; resultSummary.newThumbnailCount reports how many that run added.

Endpoints

The Thumbnail result object

transcriptionIdstring
Linked transcription (txt_…). Path param on retrieve/delete routes.
jobIdstring
Source thumbnail job.
generatedboolean
True when at least one thumbnail was persisted.
thumbnailCountnumber
Number of AI items in items[] — accumulated total across runs. Each run adds up to 3.
nonAiThumbnailCountnumber
Number of non-AI (raw frame) items in nonAiItems[] — accumulated total across runs. Each run adds up to 5.
itemsarray
Per-image metadata for AI thumbnails. Each item includes id, bucket, key, optional url (when requested via include), score (confidence 0–1), caption, variantStyle, and generatedByAi.
nonAiItemsarray
Per-image metadata for non-AI thumbnails (raw frames), same shape as items with generatedByAi: false.

List thumbnails

GET/v1/thumbnails
Lists transcriptions in the project that have generated thumbnails (thumbnails.thumbnailCount > 0).

Requires permission

transcript:list

Parameters

pageinteger, optional
Page number (default 1).
limitinteger, optional
Page size (default 20, max 100).

Returns

Returns an array of thumbnail result objects keyed by transcriptionId.

See the the thumbnail result object for attribute details.

Retrieve thumbnails for a transcription

GET/v1/thumbnails/{transcriptionId}
Returns thumbnail metadata stored on the transcription. The path parameter is the transcriptionId (txt_…), not a separate thumbnail record id.

Requires permission

transcript:read

Example thumbnail item (S3 paths):
{
      "id": "thumb_01",
      "bucket": "my-media-bucket",
      "key": "perchat-media-results/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/thumbnails/thumbnail_1.jpg",
      "score": 0.94,
      "caption": "Speaker gestures at product on stage",
      "variantStyle": "landscape",
      "generatedByAi": true
    }
With download URL (?include=thumbnailUrls on the transcript retrieve):
{
      "id": "thumb_01",
      "bucket": "my-media-bucket",
      "key": "perchat-media-results/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/thumbnails/thumbnail_1.jpg",
      "url": "https://bucket.s3.region.amazonaws.com/thumbnails/thumb_01.jpg?X-Amz-Algorithm=...",
      "score": 0.94,
      "caption": "Speaker gestures at product on stage",
      "variantStyle": "landscape",
      "generatedByAi": true
    }
Transcript-embedded shape:
{
  "generated": true,
  "thumbnailCount": 2,
  "nonAiThumbnailCount": 1,
  "jobId": "job_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "items": [
    {
      "id": "thumb_01",
      "bucket": "my-media-bucket",
      "key": "perchat-media-results/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/thumbnails/thumbnail_1.jpg",
      "score": 0.94,
      "caption": "Speaker gestures at product on stage",
      "variantStyle": "landscape",
      "generatedByAi": true
    }
  ],
  "nonAiItems": [
    {
      "id": "frame_01",
      "bucket": "my-media-bucket",
      "key": "perchat-media-results/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/thumbnails/non_ai_thumbnail_1.jpg",
      "score": 0.78,
      "caption": null,
      "variantStyle": "landscape",
      "generatedByAi": false
    }
  ]
}

Parameters

transcriptionIdstring
Transcription identifier (txt_…).

Returns

Returns a thumbnail result object.

See the the thumbnail result object for attribute details.

Clear thumbnails for a transcription

DELETE/v1/thumbnails/{transcriptionId}
Clears the thumbnails subdocument on the transcription. Does not delete images from your S3 bucket.

Requires permission

transcript:delete

Parameters

transcriptionIdstring
Transcription identifier (txt_…).

Returns

Returns a confirmation object.

See the the thumbnail result object for attribute details.