# Ximalaya (喜马拉雅)

> China's largest online audio platform — audiobooks, podcasts, radio dramas,
> children's content, courses, news and live broadcast radio. Its developer surface is
> the Ximalaya Open Platform, a partner-oriented program that lets mobile apps, smart
> speakers, in-car head units, H5 sub-sites and WeChat mini-programs embed Ximalaya
> audio.

generated: 2026-09-04
method: generated
source: Generated by API Evangelist from this repository's artifacts and Ximalaya's
  published Open Platform documentation. Ximalaya serves no llms.txt of its own
  (https://www.ximalaya.com/llms.txt and https://open.ximalaya.com/llms.txt both 404,
  probed 2026-09-04). This file is API Evangelist's description of Ximalaya, not a
  document Ximalaya publishes.

## What an agent needs to know first

- **There is no OpenAPI, Swagger, GraphQL, AsyncAPI or MCP contract.** The API is real,
  large and actively maintained, but it is documented only as HTML. Roughly 90
  operations across two hosts are described in prose and parameter tables.
- **Access is gated by commercial onboarding, not signup.** An app_key is issued only
  after a partner registers and agrees a scope of access with a Ximalaya business
  contact. There is no self-service key and no published pricing.
- **Every request must be signed.** app_key plus a per-request `sig`: sort all
  parameters, join as key=val pairs, base64 the result, HMAC-SHA1 it with the
  app_secret (concatenated with serverAuthenticateStaticKey for server-side access),
  then MD5 the **raw HMAC bytes**. Ximalaya's own docs flag the raw-bytes step as the
  most common integration error.
- **Retries are not safe.** There is no idempotency key, and replaying an identical
  signed request is rejected as a duplicate (error 225). Every retry must be re-signed
  with a fresh nonce, and no server-side deduplication exists.
- **Language.** All documentation is in Chinese.

## API hosts

- `https://api.ximalaya.com` — content, search, recommendation, broadcast radio,
  OAuth 2.0, user data, analytics callbacks
- `https://apihera.ximalaya.com` — documented manual failover for the above
- `https://mpay.ximalaya.com` — paid content, pricing, distribution, orders
- `https://mpayhera.ximalaya.com` — documented manual failover for the above
- Media bytes are served from `*.xmcdn.com` (allowlist the wildcard)

## Documentation

- [Developer portal](https://open.ximalaya.com/)
- [API reference](https://open.ximalaya.com/doc/api)
- [Quick start](https://open.ximalaya.com/doc/quickStart)
- [API access guide](https://open.ximalaya.com/doc/detailApi?categoryId=7&articleId=70)
- [Common parameters](https://open.ximalaya.com/doc/detailApi?categoryId=6&articleId=67)
- [Signature algorithm](https://open.ximalaya.com/doc/detailApi?categoryId=6&articleId=69)
- [Error codes](https://open.ximalaya.com/doc/detailApi?categoryId=6&articleId=38)
- [Data model](https://open.ximalaya.com/doc/detailApi?categoryId=6&articleId=37)
- [Server-side API debugging tool](https://open.ximalaya.com/doc/tool)
- [Create an application](https://open.ximalaya.com/developer/app)

Note for crawlers: the portal is a single-page application that returns HTTP 200 with
the same HTML shell for every path. Its documentation is served as JSON from
`https://open.ximalaya.com/api-docs`, `/docs` and `/quick-start-docs` (tree) and
`.../document?id=<id>` (article), anonymously.

## API surface

### Content — on demand
Free albums and tracks, paid album/track metadata, batch fetch, incremental sync.
`/v2/albums/list`, `/albums/get_batch`, `/albums/browse`, `/albums/get_update_batch`,
`/tracks/get_batch`, `/tracks/get_single`, `/categories/list`, `/v2/tags/list`,
`/v2/metadata/albums`, `/incr/albums`, `/incr/tracks`,
`/open_pay/batch_get_paid_albums`, `/open_pay/batch_get_paid_tracks`,
`/open_pay/browse_paid_album_tracks`

### Search and recommendation
`/v2/search/albums`, `/v2/search/tracks`, `/search/hot_words`, `/search/suggest_words`,
`/v2/albums/guess_like`, `/v2/albums/relative_albums`, `/v2/tracks/relative_albums`

### Playback
`/openapi_play_url/tracks/batch_get_play_info` (free),
`/open_pay/get_play_info`, `/open_pay/batch_get_play_info`,
`/open_pay/get_video_play_info`, `/open_pay/batch_get_video_play_info`.
Playback URLs are per-request and expire; error 702 signals an expired decryption key.

### Broadcast radio
`/live/radios`, `/live/schedules`, `/live/get_playing_program`,
`/live/get_radios_by_category`, `/live/get_radios_by_city`, `/live/radio_categories`,
`/live/provinces`, `/live/cities`

### Content operations (editorial)
`/operation/xm_columns`, `/operation/developer_columns`, `/operation/browse_column_content`,
`/operation/rank_by_type`, `/operation/dimensions`, `/operation/tags_of_dimension`,
`/operation/recommend_albums`, `/operation/xm_banners`

### Accounts (OAuth 2.0)
`/oauth2/v2/authorize`, `/oauth2/v2/access_token`, `/oauth2/refresh_token`,
`/oauth2/get_token_info`, `/oauth2/revoke_token`, `/oauth2/revoke_refresh_token`,
`/oauth2/exchange_access_token`.
Scopes: `profile:read`, `subscribe:read`, `subscribe:write`, `play_history:read`,
`play_history:write`, `open_pay:read`

### User data (requires access_token)
`/profile/user_info`, `/profile/persona`, `/v2/subscribe/get_albums_by_uid`,
`/v2/subscribe/is_subscribed`, `/subscribe/add_or_delete`, `/subscribe/batch_add`,
`/play_history/get_by_uid`, `/play_history/batch_upload`, `/play_history/batch_delete`

### Commerce and distribution (mpay host)
`/open_pay/get_price_info`, `/omp-payment-open-api/get_gradient_activity_price_info`,
`/omp-payment-open-api/get_distributed_product_infos`,
`/omp-payment-open-api/v2/distribute`, `/open_pay/v2/prepare_order`,
`/open_pay/v3/get_order_detail`, `/open_pay/get_order_records`,
`/open_pay/album_bought_status`, `/open_pay/track_bought_status`,
`/v2/open_pay/get_bought_albums`, `/open_pay/get_un_purchase_tracks`

### Event surface (HTTP callbacks, no AsyncAPI)
Inbound, Ximalaya to partner, separately signed: `/ximalaya/open_push` (shelf state),
`/ximalaya/notice_pay_album_update`, `/ximalaya/order_status_notify` (includes refunds),
`/ximalaya/upload_notify`, `/ximalaya/validate_third_token`.

Outbound and **mandatory** — a partner must implement play, album-browse and
album-impression analytics reporting, and prove it works, before an application passes
launch review. Device identifiers (OAID on Android, IDFA on iOS) must be reported on
every call.

## Limits

- 5,000 requests per minute per application, across all endpoints
- 280,000 requests per hour per application, across all endpoints
- Exhaustion returns error_no 104 in the body. **No rate-limit response headers of any
  kind, and no Retry-After.**
- A separate per-listener anti-abuse control (error 110) triggers on a single UID
  exceeding 20 albums and 8,000 track requests in a day.

## Testing

There is **no sandbox**. Ximalaya publishes two shared test credential sets that point
at production, and the test albums and tracks are real catalog items purchased with
real money. Refunds are generally not supported and must be arranged with a business
contact in advance.

## Client libraries

One first-party package on a public registry: `@xmly-fem/web-jssdk` (npm, v1.5.1,
published 2023-06-08) — browser only. iOS, Android and WeChat mini-program SDKs are
distributed through the partner console with no public version metadata. **There is no
first-party server-side SDK in any language**, so every backend integration implements
the signature by hand.

GitHub: [XimalayaCloud](https://github.com/XimalayaCloud) — first-party, but
infrastructure open source (xcache, award, aggregate-framework), not API clients.

## What Ximalaya does not publish

- No OpenAPI, Swagger, GraphQL SDL, AsyncAPI, Protobuf or WSDL
- No MCP server and no A2A agent card
- No `/.well-known` documents on any host — no security.txt, no OAuth discovery, no
  api-catalog
- No llms.txt
- No status page, SLA, changelog or deprecation policy
- No pricing or plan tiers
- No RSS/podcast feeds, no schema.org structured data, no Postman collection

## API Evangelist artifacts in this repository

- `authentication/ximalaya-authentication.yml` — signature and OAuth 2.0 profile
- `scopes/ximalaya-scopes.yml` — the six published OAuth scopes
- `errors/ximalaya-error-codes.yml` — 38 published error codes
- `rate-limits/ximalaya-rate-limits.yml` — published quotas
- `conventions/ximalaya-conventions.yml` — pagination, versioning, idempotency,
  reversibility
- `data-model/ximalaya-data-model.yml` — 56 published entities
- `asyncapi/ximalaya-callbacks-webhooks.yml` — the inbound and outbound callback catalog
- `lifecycle/ximalaya-lifecycle.yml` — versioning, deprecations, doc freshness
- `sandbox/ximalaya-sandbox.yml` — the production-only test posture
- `plans/ximalaya-plans-pricing.yml` — why there is no published pricing
- `packages/ximalaya-packages.yml` — the one public SDK and its age
- `components/ximalaya-components.yml` — JS SDK, player, H5 sub-site, mini-program plugin
- `conformance/ximalaya-conformance.yml` — standards asserted and not asserted
- `well-known/ximalaya-well-known.yml` — the 56-probe absence record
- `mcp/ximalaya-mcp.yml` — a candidate tool surface; no server exists