transcribe_media

Get the spoken words out of any audio or video in the user's account, timed and attributed to speakers.

WHAT IT TAKES. One media reference — an upload or a generation, in the exact shape list_media returns. Anything with a sound track qualifies: an uploaded video or podcast, a voice-over or music track generated here, a clip this studio rendered. Images are refused.

Up to 60 minutes of media per file. Costs no credits.

HOW IT RUNS. The first call queues the transcription and returns ready:false — call get_transcription with the same media to poll, usually a few seconds for a short clip and longer for a long one. The result is stored against the file, so once it is ready every later call returns it instantly and for free.

WHAT COMES BACK. segments are timed lines in order, each with start_seconds, end_seconds, a diarization speaker label and its text; speakers lists the distinct labels; language is what the speech model detected; text is the whole thing as prose for reading.

USING IT TO ANALYSE A VIDEO. This is the words half. measure_video is the pictures half — measured shot boundaries and keyframe images for a video upload — and the two are meant to be read together: the bundle tells you when the cuts are and what is on screen, this tells you what is being said over them and by whom. Reach for this one alone whenever the file is audio, is a generation rather than an upload, is longer than the bundle accepts, or when you need to know who spoke.

The timings and speaker labels are measured, not guessed. Quote them; never round, shift or invent one. An empty transcript is a real answer — silent footage, an instrumental track — and not a reason to retry.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "transcribe_media",
    "arguments": {
      "media": {
        "type": "upload",
        "upload_id": "00000000-0000-4000-8000-000000000000"
      }
    }
  }
}

{
  "type": "object",
  "properties": {
    "media": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "upload"
            },
            "upload_id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "type",
            "upload_id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "generation"
            },
            "generation_id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "type",
            "generation_id"
          ],
          "additionalProperties": false
        }
      ],
      "description": "The audio or video to transcribe — an upload or a generation, in the shape list_media returns."
    },
    "retry": {
      "type": "boolean",
      "description": "Run a failed transcription again. A ready transcript is never replaced; a plain call polls."
    },
    "chunk_max_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60,
      "description": "Also cut the recording at its pauses into lines of at most this many seconds (15 for an avatar clip): `chunks` gives each line's start_seconds and duration_seconds for trim_audio."
    }
  },
  "required": [
    "media"
  ],
  "additionalProperties": false
}