Podcast Transcription
tier:standard

Request an episode's transcription

Queues an episode discovered in its podcast's back catalogue (transcript_status requestable) to be transcribed. Returns 202 with the new request that queues the episode, the only outcome billed as a transcription. Returns 200, billed as a lookup, when there is nothing to transcribe: you have requested the episode before (the existing request), another organization's request already queued it (your own request, tracking it), or we already hold the episode (no request is created, and state says where its transcript stands). There is no limit on how many episodes you request. Requests are transcribed concurrently, usually within a few minutes; a large batch is worked through as earlier requests finish, with organizations served by plan and then evenly. Poll GET /v1/podcasts/transcription/requests/{id} or the episode's transcript_status. The episode keeps its ID once transcribed, and every episode endpoint then serves it. 422 episode_audio_unavailable when its audio cannot be fetched. Send an Idempotency-Key to retry safely: a retry under the same key returns the first response and is not billed.

post/v1/podcasts/transcription/requests

Request

  • Base URL: https://api.particle.pro
  • URL: https://api.particle.pro/v1/podcasts/transcription/requests
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

Idempotency-Keystring

A key you choose, such as a UUID, to retry this request safely. Resend the same key with the same request and the first response is returned with Idempotent-Replayed: true instead of the request running again, for 24 hours after it succeeded. The same key with a different request returns 422 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_key_in_use. A request that fails does not use up its key.

Request body

episode_idstring required

The episode to transcribe: the id of an episode whose transcript_status is requestable, as GET /v1/podcasts/episodes?podcast_id=…&transcript_status=requestable lists them.

Response

Nothing to transcribe, billed as a lookup: an existing request, your own request joining another organization's queue, or an episode we already hold.

admitted_atstring date-time

When transcription started.

completed_atstring date-time

When the request was transcribed or failed.

created_atstring date-time

When the request was made.

episode_idstring required

The episode, for GET /v1/podcasts/episodes/{id}. It keeps this ID once transcribed.

failure_reasonstring

Why a failed request will not be transcribed, e.g. enclosure_gone when the publisher removed the audio, or timed_out.

idstring

The request's ID, for GET /v1/podcasts/transcription/requests/{id}. Absent when no request was needed because we already hold the episode: state then reports where its transcript stands.

podcast_idstring

The episode's podcast.

refunded_atstring date-time

When a failed request's transcription charge was returned to your organization: the included request, prepaid credit or overage it drew. Absent until then, and on requests that were billed as a lookup.

state'queued' | 'admitted' | 'transcribed' | 'failed' required

queued: waiting its turn. admitted: being transcribed. transcribed: the transcript is available. failed: it will not be transcribed; failure_reason says why.

Changes

No recorded changes to this operation across all 2 revisions of this API.