---
name: plainscribe-transcription
description: Transcribe uploaded audio/video files or YouTube links through the PlainScribe API and retrieve JSON, text, Markdown, CSV, SRT, or VTT results.
homepage: https://www.plainscribe.com/developers
metadata:
  openapi: https://www.plainscribe.com/openapi.json
---

# PlainScribe Transcription

Use this skill when a user asks to transcribe, subtitle, or translate an audio/video file, or to transcribe a supported YouTube URL.

## Requirements

- A PlainScribe account with credits.
- A user API key created from the PlainScribe profile page.
- The key stored as `PLAINSCRIBE_API_KEY`. Use it only from a trusted server or local agent process; never print it, log it, or embed it in browser or mobile code.

Base URL: `https://www.plainscribe.com/api/v1`

Send every request with:

```http
Authorization: Bearer $PLAINSCRIBE_API_KEY
```

Generate an `Idempotency-Key` once for each intended POST. If the response is lost or times out, retry with that same key and unchanged request body. Use a new key only for a new upload or transcription operation.

## File workflow

1. Read the local file's basename, byte size, and MIME type.
2. `POST /uploads` with `file_name`, `size_bytes`, and `content_type`.
3. Upload bytes to the returned signed PUT URL. For files above 6MB, prefer the returned TUS resumable configuration. Use its signed endpoint (ending in `/resumable/sign`), headers, and `chunk_size_bytes` value verbatim.
4. `POST /transcriptions` with `source.type = "upload"` and the returned `upload_id`.
5. Poll the returned `links.self` every five seconds until `status` is `completed` or `failed`.
6. Fetch `links.result`. Add `?format=txt`, `md`, `csv`, `srt`, or `vtt` when the user requests that format.

Never invent `duration_seconds`; PlainScribe reads duration from the uploaded media before billing.

Accepted API upload extensions: AAC, AIF, AIFC, AIFF, AU, AVI, CAF, FLAC, M4A, M4V, MKV, MOV, MP3, MP4, MPEG, MPG, OGA, OGG, OPUS, TS, WAV, WAVE, WEBA, and WEBM.

## YouTube workflow

Call `POST /transcriptions` with:

```json
{
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "language": "auto"
  },
  "mode": "transcription"
}
```

Then poll and retrieve the result exactly as in the file workflow.

## Safety and user control

- Confirm before spending credits if the user has not explicitly asked to transcribe the media.
- Use `GET /credits` when cost or available balance matters.
- PlainScribe deletes raw uploaded media after processing and retains transcript artifacts for up to 30 days.
- Use `DELETE /transcriptions/{id}` when the user asks to remove a completed or failed transcript early.
- Do not retry `402 insufficient_credits` automatically. Tell the user that credits are required.

## Canonical reference

OpenAPI: https://www.plainscribe.com/openapi.json

Human documentation: https://www.plainscribe.com/developers