curl -X POST 'https://api.xueyuanpie.com/app/playlet/search' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":0,"keyword":"重生","page":1,"size":20}'

选择平台
   ↓
获取分类 categories（可选）
   ↓
分页列表 page / 搜索 search
   ↓
详情与剧集 detail
   ↓
若 episodes[].playUrl 为空，则调用 play
   ↓
播放 url；失败时依次尝试 backupUrls

{
  "sourceId": "7594403964322335768",
  "episodeId": "615427457"
}

{
  "sourceId": 7594403964322335768,
  "episodeId": 615427457
}

Content-Type: application/json; charset=UTF-8
Accept: application/json

{
  "code": 1000,
  "message": "success",
  "data": {}
}

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Cache-Control: no-store

{
  "code": 503,
  "message": "短剧 API 后端尚未部署，请稍后重试",
  "data": null
}

{
  "category": "题材",
  "items": [
    {
      "id": "1273",
      "name": "都市",
      "current": false
    }
  ]
}

{
  "platform": "QIMAO",
  "sourceId": "41000288558",
  "title": "短剧名称",
  "cover": "https://example.com/cover.jpg",
  "introduction": "剧情简介",
  "episodeCount": 80,
  "score": "9.3",
  "playCount": "1200万",
  "tags": ["都市", "重生"],
  "finishStatus": "已完结"
}

{
  "sourceEpisodeId": "615427457",
  "episodeNumber": 1,
  "title": "第1集",
  "cover": "https://example.com/episode-1.jpg",
  "durationSeconds": 125,
  "playable": true,
  "playUrl": null,
  "quality": "720P"
}

{
  "detail": {
    "platform": "HEMA",
    "sourceId": "41000288558",
    "title": "短剧名称",
    "cover": "https://example.com/cover.jpg",
    "introduction": "剧情简介",
    "episodeCount": 80,
    "score": null,
    "playCount": null,
    "tags": ["都市"],
    "finishStatus": "已完结"
  },
  "episodes": []
}

{
  "sourceEpisodeId": "615427457",
  "url": "https://example.com/video.m3u8?sign=...",
  "quality": "720P",
  "format": "m3u8",
  "backupUrls": [
    "https://backup.example.com/video.m3u8?sign=..."
  ]
}

{
  "list": [],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 99999
  }
}

本页 list 为空               → 已到底
本页 list.size < 请求 size   → 通常已到底
本页 list.size == 请求 size  → 可以继续请求下一页

POST /app/playlet/categories

{
  "platform": 1
}

{
  "code": 1000,
  "message": "success",
  "data": [
    {
      "category": "题材",
      "items": [
        {
          "id": "1273",
          "name": "都市",
          "current": false
        },
        {
          "id": "1274",
          "name": "重生",
          "current": false
        }
      ]
    }
  ]
}

{
  "code": 1000,
  "message": "success",
  "data": []
}

curl -X POST 'https://api.xueyuanpie.com/app/playlet/categories' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":1}'

POST /app/playlet/page

{
  "platform": 1,
  "categoryId": "1273",
  "page": 1,
  "size": 20
}

{
  "platform": 0,
  "page": 1,
  "size": 20
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "list": [
      {
        "platform": "QIMAO",
        "sourceId": "41000288558",
        "title": "重生后我走向人生巅峰",
        "cover": "https://example.com/cover.jpg",
        "introduction": "一段示例剧情简介",
        "episodeCount": 80,
        "score": "9.3",
        "playCount": "1200万",
        "tags": ["都市", "重生"],
        "finishStatus": "已完结"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 99999
    }
  }
}

curl -X POST 'https://api.xueyuanpie.com/app/playlet/page' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":1,"categoryId":"1273","page":1,"size":20}'

POST /app/playlet/search

{
  "platform": 0,
  "keyword": "重生",
  "page": 1,
  "size": 20
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "list": [
      {
        "platform": "HONGGUO",
        "sourceId": "7594403964322335768",
        "title": "重生之示例短剧",
        "cover": "https://example.com/hongguo-cover.jpg",
        "introduction": "搜索结果示例",
        "episodeCount": 60,
        "score": null,
        "playCount": "热播",
        "tags": ["重生"],
        "finishStatus": "已完结"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 99999
    }
  }
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 99999
    }
  }
}

{
  "code": 400,
  "message": "搜索关键词不能为空",
  "data": null
}

curl -X POST 'https://api.xueyuanpie.com/app/playlet/search' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":0,"keyword":"重生","page":1,"size":20}'

POST /app/playlet/detail

{
  "platform": 2,
  "sourceId": "41000288558"
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "detail": {
      "platform": "HEMA",
      "sourceId": "41000288558",
      "title": "示例短剧",
      "cover": "https://example.com/cover.jpg",
      "introduction": "剧情简介",
      "episodeCount": 2,
      "score": "9.0",
      "playCount": "100万",
      "tags": ["都市"],
      "finishStatus": "已完结"
    },
    "episodes": [
      {
        "sourceEpisodeId": "615427457",
        "episodeNumber": 1,
        "title": "第1集",
        "cover": "https://example.com/episode-1.jpg",
        "durationSeconds": 125,
        "playable": true,
        "playUrl": null,
        "quality": "720P"
      },
      {
        "sourceEpisodeId": "615427458",
        "episodeNumber": 2,
        "title": "第2集",
        "cover": null,
        "durationSeconds": 132,
        "playable": true,
        "playUrl": "https://example.com/direct-video.m3u8?sign=...",
        "quality": "720P"
      }
    ]
  }
}

curl -X POST 'https://api.xueyuanpie.com/app/playlet/detail' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":2,"sourceId":"41000288558"}'

POST /app/playlet/play

{
  "platform": 2,
  "sourceId": "41000288558",
  "episodeId": "615427457"
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "sourceEpisodeId": "615427457",
    "url": "https://example.com/video.m3u8?sign=...",
    "quality": "720P",
    "format": "m3u8",
    "backupUrls": [
      "https://backup-1.example.com/video.m3u8?sign=...",
      "https://backup-2.example.com/video.m3u8?sign=..."
    ]
  }
}

{
  "code": 1000,
  "message": "success",
  "data": {
    "sourceEpisodeId": "615427457",
    "url": null,
    "quality": null,
    "format": null,
    "backupUrls": []
  }
}

curl -X POST 'https://api.xueyuanpie.com/app/playlet/play' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{"platform":2,"sourceId":"41000288558","episodeId":"615427457"}'

data class PlatformRequest(
    val platform: Int
)

data class PageRequest(
    val platform: Int,
    val categoryId: String? = null,
    val page: Int = 1,
    val size: Int = 20
)

data class SearchRequest(
    val platform: Int,
    val keyword: String,
    val page: Int = 1,
    val size: Int = 20
)

data class DetailRequest(
    val platform: Int,
    val sourceId: String
)

data class PlayRequest(
    val platform: Int,
    val sourceId: String,
    val episodeId: String
)

data class ApiResponse<T>(
    val code: Int,
    val message: String? = null,
    val msg: String? = null,
    val data: T? = null
) {
    fun displayMessage(): String = message ?: msg ?: "请求失败"
}

data class Pagination(
    val page: Long = 1,
    val size: Long = 20,
    val total: Long = 0
)

data class PageResult<T>(
    val list: List<T> = emptyList(),
    val pagination: Pagination = Pagination()
)

data class PlayletItem(
    val platform: String? = null,
    val sourceId: String? = null,
    val title: String? = null,
    val cover: String? = null,
    val introduction: String? = null,
    val episodeCount: Int? = null,
    val score: String? = null,
    val playCount: String? = null,
    val tags: List<String> = emptyList(),
    val finishStatus: String? = null
)

data class Episode(
    val sourceEpisodeId: String? = null,
    val episodeNumber: Int? = null,
    val title: String? = null,
    val cover: String? = null,
    val durationSeconds: Long? = null,
    val playable: Boolean = true,
    val playUrl: String? = null,
    val quality: String? = null
)

data class PlayletDetail(
    val detail: PlayletItem? = null,
    val episodes: List<Episode> = emptyList()
)

data class PlayletPlay(
    val sourceEpisodeId: String? = null,
    val url: String? = null,
    val quality: String? = null,
    val format: String? = null,
    val backupUrls: List<String> = emptyList()
)

interface PlayletApi {
    @POST("app/playlet/categories")
    suspend fun categories(
        @Body body: PlatformRequest
    ): ApiResponse<List<Map<String, Any?>>>

    @POST("app/playlet/page")
    suspend fun page(
        @Body body: PageRequest
    ): ApiResponse<PageResult<PlayletItem>>

    @POST("app/playlet/search")
    suspend fun search(
        @Body body: SearchRequest
    ): ApiResponse<PageResult<PlayletItem>>

    @POST("app/playlet/detail")
    suspend fun detail(
        @Body body: DetailRequest
    ): ApiResponse<PlayletDetail>

    @POST("app/playlet/play")
    suspend fun play(
        @Body body: PlayRequest
    ): ApiResponse<PlayletPlay>
}

val okHttpClient = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS)
    .build()

val api = Retrofit.Builder()
    .baseUrl("https://api.xueyuanpie.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
    .create(PlayletApi::class.java)

suspend fun resolveEpisodeUrl(
    api: PlayletApi,
    platform: Int,
    sourceId: String,
    episode: Episode
): List<String> {
    if (!episode.playable) return emptyList()

    // 详情已直接给出地址时先使用它。
    episode.playUrl?.takeIf { it.isNotBlank() }?.let {
        return listOf(it)
    }

    val episodeId = episode.sourceEpisodeId
        ?: return emptyList()

    val response = api.play(
        PlayRequest(platform, sourceId, episodeId)
    )
    if (response.code != 1000) {
        throw IllegalStateException(response.displayMessage())
    }

    val play = response.data ?: return emptyList()
    return buildList {
        play.url?.takeIf { it.isNotBlank() }?.let(::add)
        addAll(play.backupUrls.filter { it.isNotBlank() })
    }.distinct()
}

MediaType JSON = MediaType.get("application/json; charset=utf-8");
String bodyJson = "{\"platform\":2,\"sourceId\":\"41000288558\"}";

Request request = new Request.Builder()
    .url("https://api.xueyuanpie.com/app/playlet/detail")
    .header("Accept", "application/json")
    .post(RequestBody.create(bodyJson, JSON))
    .build();

try (Response response = okHttpClient.newCall(request).execute()) {
    String responseText = response.body() == null
        ? ""
        : response.body().string();

    if (!response.isSuccessful()) {
        throw new IOException(
            "HTTP " + response.code() + ": " + responseText
        );
    }

    // 使用 Gson/Jackson 解析 ApiResponse<PlayletDetail>。
    // 先判断 code，再读取 data；提示兼容 message 和 msg。
}

type ApiResponse<T> = {
  code: number;
  message?: string;
  msg?: string;
  data: T | null;
};

type DetailRequest = {
  platform: 0 | 1 | 2;
  sourceId: string; // 必须是 string
};

async function postPlaylet<T>(path: string, body: unknown): Promise<T> {
  const response = await fetch(`https://api.xueyuanpie.com${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json; charset=UTF-8",
      "Accept": "application/json"
    },
    body: JSON.stringify(body)
  });

  const result = await response.json() as ApiResponse<T>;
  if (!response.ok) {
    throw new Error(result.message ?? result.msg ?? `HTTP ${response.status}`);
  }
  if (result.code !== 1000 || result.data == null) {
    throw new Error(result.message ?? result.msg ?? "业务请求失败");
  }
  return result.data;
}

const detail = await postPlaylet(
  "/app/playlet/detail",
  { platform: 2, sourceId: "41000288558" } satisfies DetailRequest
);

发生时间（含时区）：
接口路径：
platform：
HTTP 状态：
业务 code：
提示信息：
请求耗时：
是否可稳定复现：
脱敏后的 sourceId / episodeId：