Transcription API

Submit audio for transcription and retrieve results via the Plaud Transcription API.

Regions

All partner endpoints — OAuth, SDK, file upload, and transcription — are served from the regional sub-station. There is no global host for these calls; pick the host of the region your client was provisioned in and use it for every step that follows.

Region	Public host	Status
US	platform-us.plaud.ai	Available
Japan	platform-jp.plaud.ai	Available
Europe	platform-eu.plaud.ai	Coming soon
Singapore	platform-sg.plaud.ai	Coming soon

Every example below omits the host. Prepend https://platform-<region>.plaud.ai/developer/api to each path. The client_id and secret_key issued by the Portal are also region-scoped, so all subsequent calls must target the same regional host.

---

Authentication

Before submitting audio, your backend has to walk through two token exchanges. The result is a user access token used to initialize the SDK and upload files, plus an api_key used to call the transcription endpoints.

Step 1 — Exchange credentials for a partner access token

Client-level token. Used to mint per-user tokens.

POST /oauth/partner/access-token
Authorization: Basic base64(client_id:secret_key)
Content-Type: application/x-www-form-urlencoded

{
  "access_token": "eyJhbGciOiJSUz...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 3600
}

Refresh before expiry:

POST /oauth/partner/access-token/refresh
Authorization: Basic base64(client_id:secret_key)
Content-Type: application/x-www-form-urlencoded

refresh_token=<refresh_token>

Step 2 — Exchange the partner token for a user access token

User-level token. This is what the SDK and file upload endpoints accept.

POST /open/partner/users/access-token
Authorization: Bearer <partner_access_token>
Content-Type: application/json

{
  "user_id": "<your stable user id, 6-120 chars>",
  "expires_in": 86400
}

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

Initialize the SDK with this access_token (see iOS SDK).

---

Submit Audio

Recommended authentication: API key headers. The api_key is issued alongside client_id / secret_key in the Portal.

POST /open/partner/ai/transcriptions/
X-Client-Id: <client_id>
X-Client-Api-Key: <api_key>
Content-Type: application/json

{
  "file_url": "<DownloadUrl from file upload>",
  "params": {
    "transcribe":  { "language": "auto", "model": "plaud-fast-whisper" },
    "vad":         { "decode_silence": false },
    "diarization": { "enabled": false, "return_embedding": false }
  }
}

Body parameters

Parameter	Type	Required	Description
file_url	string	Yes	Pre-signed download URL returned by complete-upload (M4A, MP3, WAV)
params.transcribe.language	string	No	BCP-47 code (en, ja, zh); defaults to auto
params.transcribe.model	string	No	Defaults to plaud-fast-whisper
params.diarization.enabled	boolean	No	Identify and label speakers; default: false

Response

{
  "transcription_id": "task_exec_xxx",
  "status": "PENDING",
  "data": {}
}

---

Get Results

GET /open/partner/ai/transcriptions/{transcription_id}
X-Client-Id: <client_id>
X-Client-Api-Key: <api_key>

{
  "transcription_id": "task_exec_xxx",
  "status": "SUCCESS",
  "data": {
    "text": "Meeting started at 10am...",
    "language": "en",
    "duration": 1843,
    "segments": [
      {
        "start": 0.0,
        "end": 4.2,
        "text": "Meeting started at 10am.",
        "speaker": "Speaker 1"
      }
    ]
  }
}

Status values

Status	Meaning
PENDING / RECEIVED / STARTED / PROGRESS	In progress — keep polling
SUCCESS	Ready — data populated
FAILURE / REVOKED	Terminal failure