> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transcriptmagic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify Podcasts

> Transcribe a Spotify podcast episode with an async submit + poll flow.

```http theme={null}
POST https://api.transcriptmagic.com/api/podcast/transcript
GET  https://api.transcriptmagic.com/api/podcast/jobs/{jobId}
```

Podcast transcription is **asynchronous**. You submit a Spotify episode URL, receive a `jobId`, then poll until the transcript is ready. Because podcasts rarely ship captions, the transcript is generated with AI speech-to-text from the episode's audio (resolved from the show's RSS feed).

> [!NOTE]
>
> Podcast transcription is available on the **Plus** and **Pro** plans. A key on the Free or Starter plan, or a legacy one-time credit purchase, receives `402 upgrade_required`. Billing is **10 credits per audio-hour** (rounded up, with a short grace window), reserved when the job is submitted and refunded automatically if the job fails.

## Step 1 — Submit a job

```bash cURL theme={null}
curl -X POST https://api.transcriptmagic.com/api/podcast/transcript \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk"}'
```

```python Python theme={null}
import requests

resp = requests.post(
    "https://api.transcriptmagic.com/api/podcast/transcript",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk"},
)
job = resp.json()
print(job["jobId"], job["status"])  # e.g. "abc123" "processing"
```

```javascript JavaScript theme={null}
const resp = await fetch("https://api.transcriptmagic.com/api/podcast/transcript", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk" }),
});
const job = await resp.json();
console.log(job.jobId, job.status); // "abc123" "processing"
```

```go Go theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"url": "https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk",
	})
	req, _ := http.NewRequest("POST",
		"https://api.transcriptmagic.com/api/podcast/transcript",
		bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var job struct {
		JobID  string `json:"jobId"`
		Status string `json:"status"`
	}
	json.NewDecoder(resp.Body).Decode(&job)
	fmt.Println(job.JobID, job.Status)
}
```

```php PHP theme={null}
<?php
$ch = curl_init('https://api.transcriptmagic.com/api/podcast/transcript');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk',
]));
$job = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $job['jobId'], ' ', $job['status'];
```

A submitted job returns **`202 Accepted`**:

```json theme={null}
{
  "jobId": "abc123",
  "status": "processing"
}
```

> [!NOTE]
>
> If the same episode was already transcribed (by any user), the API skips the queue and returns **`200`** immediately with the finished transcript and `"deduped": true`. Always check `status` before deciding to poll.

## Step 2 — Poll for the transcript

Poll `GET /api/podcast/jobs/{jobId}` every few seconds until `status` is `done` (or `failed`). Episodes transcribe in well under real time.

```bash cURL theme={null}
curl https://api.transcriptmagic.com/api/podcast/jobs/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python Python theme={null}
import time, requests

def wait_for_transcript(job_id, key):
    while True:
        r = requests.get(
            f"https://api.transcriptmagic.com/api/podcast/jobs/{job_id}",
            headers={"Authorization": f"Bearer {key}"},
        ).json()
        if r["status"] == "done":
            return r["transcript"]
        if r["status"] == "failed":
            raise RuntimeError(r["error"]["message"])
        time.sleep(5)

print(wait_for_transcript("abc123", "YOUR_API_KEY"))
```

```javascript JavaScript theme={null}
async function waitForTranscript(jobId, key) {
  while (true) {
    const r = await fetch(
      `https://api.transcriptmagic.com/api/podcast/jobs/${jobId}`,
      { headers: { Authorization: `Bearer ${key}` } },
    ).then((res) => res.json());
    if (r.status === "done") return r.transcript;
    if (r.status === "failed") throw new Error(r.error.message);
    await new Promise((res) => setTimeout(res, 5000));
  }
}

console.log(await waitForTranscript("abc123", "YOUR_API_KEY"));
```

```go Go theme={null}
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

func main() {
	key := "YOUR_API_KEY"
	jobID := "abc123"
	for {
		req, _ := http.NewRequest("GET",
			"https://api.transcriptmagic.com/api/podcast/jobs/"+jobID, nil)
		req.Header.Set("Authorization", "Bearer "+key)
		resp, _ := http.DefaultClient.Do(req)

		var r struct {
			Status     string `json:"status"`
			Transcript string `json:"transcript"`
			Error      struct{ Message string } `json:"error"`
		}
		json.NewDecoder(resp.Body).Decode(&r)
		resp.Body.Close()

		if r.Status == "done" {
			fmt.Println(r.Transcript)
			return
		}
		if r.Status == "failed" {
			fmt.Println("failed:", r.Error.Message)
			return
		}
		time.Sleep(5 * time.Second)
	}
}
```

```php PHP theme={null}
<?php
$key = 'YOUR_API_KEY';
$jobId = 'abc123';
while (true) {
    $ch = curl_init("https://api.transcriptmagic.com/api/podcast/jobs/$jobId");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $key"]);
    $r = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if ($r['status'] === 'done') { echo $r['transcript']; break; }
    if ($r['status'] === 'failed') { echo 'failed: ' . $r['error']['message']; break; }
    sleep(5);
}
```

### While processing

```json theme={null}
{
  "jobId": "abc123",
  "status": "processing",
  "progress": { "chunksDone": 3, "chunksTotal": 8 },
  "episode": {
    "title": "The Episode Title",
    "showTitle": "The Show",
    "artworkUrl": "https://…/artwork.jpg",
    "durationSeconds": 4051
  },
  "createdAt": "2026-07-05T19:00:00.000Z",
  "completedAt": null
}
```

### When done

```json theme={null}
{
  "jobId": "abc123",
  "status": "done",
  "progress": { "chunksDone": 8, "chunksTotal": 8 },
  "episode": {
    "title": "The Episode Title",
    "showTitle": "The Show",
    "artworkUrl": "https://…/artwork.jpg",
    "durationSeconds": 4051
  },
  "transcript": "Welcome back to the show. Today we're talking about…",
  "credits": 2940,
  "createdAt": "2026-07-05T19:00:00.000Z",
  "completedAt": "2026-07-05T19:00:42.000Z"
}
```

### When failed

```json theme={null}
{
  "jobId": "abc123",
  "status": "failed",
  "error": {
    "code": "transcription_failed",
    "message": "This episode's audio could not be retrieved"
  }
}
```

`credits` reflects your remaining balance after the reservation settles; failed jobs are refunded automatically.

## Supported URL formats

| Format | Example |
| - | - |
| Episode link | `https://open.spotify.com/episode/4rOoJ6Egrf8K2IrywzwOMk` |

Paste an individual **episode** URL. Show, playlist, or artist links don't identify a single episode and are rejected with `400`.

## FAQ

> [accordion] How long should I wait between polls?
>
> Every 3–5 seconds is plenty. Most episodes finish in seconds to a couple of minutes depending on length; a multi-hour episode is streamed through a container and still finishes far faster than real time.

> [accordion] How is billing calculated?
>
> 10 credits per audio-hour, rounded up, with a short grace window on the first few minutes. A 30-minute episode is 10 credits; a 2-hour episode is 20. Credits are reserved at submit and refunded if the job fails.

> [accordion] Why did I get 402 upgrade\_required?
>
> Podcast transcription is a Plus/Pro feature. Keys on the Free or Starter plan, or a legacy one-time credit purchase, can still use every social-video endpoint, but not the podcast endpoint. Upgrade at [transcriptmagic.com/credits](https://transcriptmagic.com/credits).

> [accordion] Are transcripts timestamped?
>
> No. Podcast transcripts are returned as plain text. `episode.durationSeconds` gives the total episode length.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.