# Spotify 播客 API (spotify.podcast)

- Canonical page: [https://everyinfra.com/spotify-api/podcast](https://everyinfra.com/spotify-api/podcast?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "spotify", "action": "podcast", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

Spotify 播客接口按 `keyword` 搜索播客，`content_type` 选 `podcasts_shows` 查节目，选 `podcast_episodes_individual_episodes` 查单集；不传时默认搜节目。每行带名称 `name`、发行方 `publisher`、剧集数量 `episode_count`、简介 `text` 和链接 `url`。它回答「这个主题下有哪些播客节目、哪些单集」，适合选题调研和竞品节目梳理。

`publisher` 和 `episode_count` 是播客专用字段。不指定数量时返回 20 条，上限 100 条。关键词搜索那一页的参数和返回字段与这个接口相同，只是 `content_type` 换成了别的取值。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=spotify&action=podcast

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | search 的音乐检索词，类型由 content_type 选择；podcast 默认搜索播客节目，不是单集详情查询。 |
| content_type | enum: podcast_episodes_individual_episodes / podcasts_shows | no | not declared | search 使用 tracks、artists、albums、playlists；podcast 仅使用 podcasts_shows（节目）或 podcast_episodes_individual_episodes（单集）。不可跨 action 混用。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| type | 记录类型，取值随能力而定（如 video / image / text）。 |
| name | 名称。用于账号/商品/商家类能力，指该对象本身的名字。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| artists | 参与艺人列表。 |
| album_name | 专辑名称。 |
| owner_name | 歌单创建者（歌单类结果用）。 |
| publisher | 发行方（播客用）。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| duration_ms | 时长，**单位毫秒**（不是秒，除以 1000 才是秒）。 |
| play_count | 播放次数。 |
| follower_count | 粉丝数。null 表示不公开，不等于 0。 |
| monthly_listener_count | 月听众数。这是 Spotify 上衡量艺人热度的核心指标。 |
| track_count | 曲目总数。 |
| episode_count | 剧集数量（播客用）。 |
| release_date | 发行日期。 |
| is_explicit | 是否含限制级内容。 |
| preview_url | 30 秒试听片段链接，可能为 null。 |
| rank | 排行榜名次。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "spotify",
  "action": "podcast",
  "params": {
    "keyword": "true crime"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "spotify",
        "action": "podcast",
        "params": {
            "keyword": "true crime",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "spotify",
  "action": "podcast",
  "results": [
    {
      "id": "5YNYcVmxKGsd8Q73mssWT9",
      "url": "https://open.spotify.com/show/5YNYcVmxKGsd8Q73mssWT9",
      "type": "show",
      "name": "Canadian True Crime",
      "text": "From the snowy streets of small-town Canada to the darkest corners of the big cities, join Aussie-Canadian host Kristi Lee for an immersive deep dive into the nation's most compelling crimes.With meticulous research and a trauma-informed approach, Kristi takes you beyond the head…",
      "image_url": "https://i.scdn.co/image/ab6765630000ba8a42c23d101ed9e52c6592c869",
      "episode_count": 240,
      "rank": 1,
      "platform": "spotify"
    },
    {
      "id": "3DgfoleqaW61T2amZQKINx",
      "url": "https://open.spotify.com/show/3DgfoleqaW61T2amZQKINx",
      "type": "show",
      "name": "Crime Junkie",
      "text": "Does hearing about a true crime case always leave you scouring the internet for the truth behind the story? Dive into your next mystery with Crime Junkie. Every Monday, join your host Ashley Flowers as she unravels all the details of infamous and underreported true crime cases wi…",
      "image_url": "https://i.scdn.co/image/ab6765630000ba8abe2cc3efd92b817b54d9bcb2",
      "episode_count": 530,
      "rank": 2,
      "platform": "spotify"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 查节目和查单集怎么选？

`content_type` 传 `podcasts_shows` 查节目，传 `podcast_episodes_individual_episodes` 查单集。`keyword` 是检索词，不是单集详情查询。看节目用 `episode_count` 知道出了多少集，看单集用 `duration_ms` 知道有多长。

### `content_type` 能不能填 tracks 或 artists？

不能。`content_type` 不可跨接口混用：播客接口只认 `podcasts_shows` 和 `podcast_episodes_individual_episodes`，tracks、artists、albums、playlists 属于关键词搜索。想搜歌曲或艺人，请改用关键词搜索。

### 单集时长怎么换算？

`duration_ms` 的单位是毫秒，不是秒，除以 1000 才得到秒。做时长统计前先换算，否则会差一千倍。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=spotify
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
