Introduction

The Perchat Media API runs transcription and related media jobs inside a workspace → project hierarchy. Authenticate with API keys from the dashboard or provision keys programmatically using a workspace admin key.

Overview

v1 supports transcription, clips, thumbnail, metadata, and indexer jobs, plus catalog search over indexed transcripts, and transcripts, and segment edits on stored transcripts with revision-checked PATCH. More service types slot in without changing the request envelope or auth model.

All endpoints live under /v1/. JSON in, JSON out. Field names are camelCase on every public route — including /v1/catalog/* (semantic search and index inventory), where the Node API normalizes catalog worker payloads before responding. Successful responses wrap payloads in { data, metadata }; errors set data to null and include an error field.

Authenticate with Authorization: Bearer <secret>. There are two key types:

  • Workspace keys (sk_wsp_…) — create projects and project API keys. Cannot submit jobs.
  • Project keys (sk_prj_…) — jobs, transcripts, storage connections, glossary, and semantic search for one project. The project is bound to the key automatically.
Base URL: https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net

Quickstart

Fast path (dashboard): if you already have a project in the sidebar, create a project key and submit a job.

1. Create a project API key

In the dashboard, open Project → Project keys (select a project first). Create a key with at least job:create and job:read. Copy data.secret when shown — it is only returned once.

2. Submit a transcription job

Submit a new transcription job and get a job ID to track the status.

options.language is optional — omit it and the API auto-detects the language from the audio. See Create a transcription job for all request fields.

Free workspaces are limited to 10 transcription jobs per billing month and sources up to 1 hour — see Plans & limits for quotas, failure codes, and transcript size policy.

Submit a Job
curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
-d '{
  "serviceType": "transcription",
  "input": {
    "sourceType": "s3_direct",
    "connectionId": "e7b2c4d8-0000-4000-a000-000000000001",
    "bucket": "my-bucket",
    "sourceKey": "media/clips/demo.mp4",
    "options": {
      "language": "en"
    }
  },
  "userMetadata": {
    "customerJobRef": "abc-123"
  }
}'
Response
{
  "jobId": "job_1234567890abcdef",
  "status": "queued",
  "serviceType": "transcription"
}

3. Check job status

Poll GET /v1/jobs/{jobId} until status is completed, failed, or cancelled.

Once completed, fetch the transcript via the Transcripts API. Queue priority is assigned from your workspace plan (free → low lane) — do not send priority in the request body.

Check Job Status
curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $API_KEY"
Response
{
  "jobId": "job_1234567890abcdef",
  "status": "completed",
  "serviceType": "transcription",
  "output": {
    "srtUrl": "https://...",
    "transcriptUrl": "https://..."
  }
}

What's next?

To generate structured metadata (title, description, chapters), complete a transcription first, then submit a metadata job with input.transcriptionId — see Create a metadata job and the Metadata resource.

To generate AI thumbnails, complete a transcription first, then submit a thumbnail job with input.transcriptionId and input.options.thumbnailCount (1–3; maximum 3 per job) — see Create a thumbnail job and the Thumbnails resource.

To search speech semantically, index completed transcripts with an indexer job, then call POST /v1/catalog/search — see Jobs & transcripts workflows → Semantic search workflow and the Semantic search resource for response fields (groups[], results[]).

Automation path (workspace key)

For CI or provisioning scripts, start with a workspace admin key from Workspace → Workspace keys (dashboard only — workspace keys cannot be created via this public API). Grant project:create and project_api_key:create, then:

  1. GET /v1/workspace — read workspace details and usage; GET /v1/projects — list projects; POST /v1/projects — create a project
  2. POST .../projects/{projectId}/api-keys — mint a project key
  3. Use the sk_prj_… secret for jobs and transcripts

See Authentication → Provision with a workspace key for full curl examples.