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, which counts as 100 requests against your monthly request usage. 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/ 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

cURL

cURL

curl -X POST \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "episode_id": "5HZ8M9tlTQ0yTgtObZ5zJs"
}' \
  "https://api.particle.pro/v1/podcasts/transcription/requests"

200

{
  "episode_id": "<string>",
  "state": "queued",
  "admitted_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "episode": {
    "id": "<string>",
    "title": "<string>",
    "podcast": {
      "id": "<string>",
      "title": "<string>",
      "best_rank": {
        "captured_at": "2023-11-07T05:31:56Z",
        "chart_type": "top_podcasts",
        "rank": 123,
        "source": "apple",
        "category_slug": "<string>",
        "country": "<string>"
      },
      "image_url": "<string>",
      "popularity": 123,
      "publisher": {
        "id": "<string>",
        "name": "<string>",
        "slug": "<string>"
      },
      "slug": "<string>"
    },
    "published_at": "2023-11-07T05:31:56Z",
    "slug": "<string>",
    "web_url": "<string>"
  },
  "failure_reason": "<string>",
  "id": "<string>",
  "podcast": {
    "id": "<string>",
    "title": "<string>",
    "best_rank": {
      "captured_at": "2023-11-07T05:31:56Z",
      "chart_type": "top_podcasts",
      "rank": 123,
      "source": "apple",
      "category_slug": "<string>",
      "country": "<string>"
    },
    "image_url": "<string>",
    "popularity": 123,
    "publisher": {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>"
    },
    "slug": "<string>"
  },
  "podcast_id": "<string>",
  "refunded_at": "2023-11-07T05:31:56Z"
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Headers

Idempotency-Key · string

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.

Required string length: 8 - 128

Body

application/json

episode_id · string · 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

200

application/json

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

episode_id · string · required

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

state · enum<string> · required

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

Available options: queued, admitted, transcribed, failed

admitted_at · string<date-time>

When transcription started.

completed_at · string<date-time>

When the request was transcribed or failed.

created_at · string<date-time>

When the request was made.

episode · object

The episode's id, title and publication date, so a list can be read without looking each one up. slug is set once the episode is transcribed or being transcribed, and absent if it was since removed. Its podcast is the podcast field beside it, not episode.podcast.

Show child attributes

failure_reason · string

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

id · string

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 · object

The episode's podcast, with its slug and title. Absent if the podcast was removed from the catalogue.

Show child attributes

podcast_id · string

The episode's podcast.

refunded_at · string<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.