Summarizations

A Summarization record provides comprehensive AI-generated synopses, SEO meta descriptions, social media hooks, keywords, and a content classification — all derived from a completedtranscription job and its natively generated visual analysis chunks. The volume of generated items (such as the number of keywords or hooks) is dynamically configured based on your workspace's billing plan.

Create a summarization job with POST /v1/jobs (serviceType: summarization). Poll GET /v1/jobs/:jobId until status: completed. Use resultSummary.summarizationId from the job to retrieve the full Summarization record with the endpoints below.

Retrieve a summarizationGET/v1/summarizations/{summarizationId}chevron_right
Update a summarizationPATCH/v1/summarizations/{summarizationId}chevron_right
Delete a summarizationDELETE/v1/summarizations/{summarizationId}chevron_right

The Summarization object

summarizationIdstring: Unique identifier (sum_…).
jobIdstring: The summarization worker job ID that produced this record.
workspaceIdstring: Owning workspace.
projectIdstring: Project scope.
shortSynopsisstring: A concise overview of the video. The maximum character length is determined by your plan configuration.
longSynopsisstring: A detailed description of the video. The maximum character length is determined by your plan configuration.
seoMetaDescriptionsstring[]: An array of distinct SEO-friendly meta description strings (each under 160 characters). The maximum number of items is determined by your plan configuration.
socialMediaHooksstring[]: An array of engaging social media hooks optimized for platforms like Twitter, TikTok, and Instagram. The maximum number of items is determined by your plan configuration.
keywordsstring[]: An array of distinct, highly relevant keywords extracted from the content. The maximum number of items is determined by your plan configuration.
classificationobject | null: Content classification with three fields: videoType (music_video | movie_trailer | podcast | tutorial | comedy | interview | sports | other), genre (action | drama | comedy | tutorial | music | sports | talk | other), and tone (cinematic | informative | educational | funny | serious | tense | dramatic | other).
createdAttimestamp: When the record was created.
updatedAttimestamp: Last update time.

{
  "summarizationId": "sum_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "shortSynopsis": "A concise overview of the video...",
  "longSynopsis": "A detailed 1-2 paragraph description...",
  "seoMetaDescriptions": [
    "Catchy SEO-friendly meta description 1",
    "Alternative SEO-friendly meta description 2",
    "Third SEO-friendly meta description 3"
  ],
  "socialMediaHooks": [
    "Engaging, high-energy hook for Twitter",
    "Second social media hook with hashtags",
    "Third hook optimized for Instagram"
  ],
  "keywords": [
    "keyword1",
    "keyword2",
    "keyword3",
    "keyword4",
    "keyword5"
  ],
  "classification": {
    "videoType": "music_video",
    "genre": "music",
    "tone": "cinematic"
  },
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
}

Retrieve a summarization

GET/v1/summarizations/{summarizationId}

Returns one Summarization by its summarizationId.

Requires permission

transcript:read

Parameters

summarizationIdstring: Summarization identifier (sum_…).

Returns

Returns a Summarization object.

See the the summarization object for attribute details.

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

{
  "data": {
  "summarizationId": "sum_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "shortSynopsis": "A concise overview of the video...",
  "longSynopsis": "A detailed 1-2 paragraph description...",
  "seoMetaDescriptions": [
    "Catchy SEO-friendly meta description 1",
    "Alternative SEO-friendly meta description 2",
    "Third SEO-friendly meta description 3"
  ],
  "socialMediaHooks": [
    "Engaging, high-energy hook for Twitter",
    "Second social media hook with hashtags",
    "Third hook optimized for Instagram"
  ],
  "keywords": [
    "keyword1",
    "keyword2",
    "keyword3",
    "keyword4",
    "keyword5"
  ],
  "classification": {
    "videoType": "music_video",
    "genre": "music",
    "tone": "cinematic"
  },
  "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"
  }
}

Update a summarization

PATCH/v1/summarizations/{summarizationId}

Updates the editable fields of a Summarization record. You can use this to save manual edits to AI-generated synopses, meta descriptions, hooks, or keywords.

Requires permission

transcript:write

Parameters

summarizationIdstring: Summarization identifier (sum_…).
shortSynopsisstring, optional: A concise overview of the video. The length must not exceed the configured limits of your plan.
longSynopsisstring, optional: A detailed description of the video. The length must not exceed the configured limits of your plan.
seoMetaDescriptionsstring[], optional: An array of distinct SEO-friendly meta description strings. The number of items provided must not exceed the configured limits of your plan.
socialMediaHooksstring[], optional: An array of engaging social media hooks. The number of items provided must not exceed the configured limits of your plan.
keywordsstring[], optional: An array of relevant keywords. The number of items provided must not exceed the configured limits of your plan.
classificationobject, optional: Content classification object with three fields: videoType (music_video | movie_trailer | podcast | tutorial | comedy | interview | sports | other), genre (action | drama | comedy | tutorial | music | sports | talk | other), and tone (cinematic | informative | educational | funny | serious | tense | dramatic | other).

Returns

Returns the updated Summarization object.

See the the summarization object for attribute details.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/summarizations/sum_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..." \
  -H "Content-Type: application/json" \
-d '"{\n  \"shortSynopsis\": \"An updated concise overview of the video.\"\n}"'

{
  "data": {
  "summarizationId": "sum_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "jobId": "job_01HZ2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": "wks_01HX...",
  "projectId": "prj_01HX...",
  "shortSynopsis": "A concise overview of the video...",
  "longSynopsis": "A detailed 1-2 paragraph description...",
  "seoMetaDescriptions": [
    "Catchy SEO-friendly meta description 1",
    "Alternative SEO-friendly meta description 2",
    "Third SEO-friendly meta description 3"
  ],
  "socialMediaHooks": [
    "Engaging, high-energy hook for Twitter",
    "Second social media hook with hashtags",
    "Third hook optimized for Instagram"
  ],
  "keywords": [
    "keyword1",
    "keyword2",
    "keyword3",
    "keyword4",
    "keyword5"
  ],
  "classification": {
    "videoType": "music_video",
    "genre": "music",
    "tone": "cinematic"
  },
  "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"
  }
}

Delete a summarization

DELETE/v1/summarizations/{summarizationId}

Deletes a Summarization record.

Requires permission

transcript:write

Parameters

summarizationIdstring: Summarization identifier (sum_…).

Returns

Returns an object confirming deletion: { summarizationId: "...", deleted: true }

See the the summarization object for attribute details.

curl -X DELETE "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/summarizations/sum_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "summarizationId": "sum_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "deleted": true
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}