{
  "openapi": "3.0.3",
  "info": {
    "title": "AI 搜歌 API · 聚合音乐搜索",
    "version": "1.2.0",
    "description": "浙江嗨做科技（AIfuture 平台 https://www.ouraiw.com）开发的聚合音乐搜索 API。一次搜索酷我、酷狗、网易云、iTunes、Audius 五大音源；支持一键榜单（90后/80后/00后热歌榜、2026-1990 逐年榜、Billboard/公信榜/Melon 海外榜）、播放地址解析、音频流代理、MP3 下载与自动换源。全部接口公开、免鉴权、支持 CORS，可被任意 AI 助手、智能体与爬虫直接调用。",
    "contact": {
      "name": "浙江嗨做科技",
      "url": "https://www.ouraiw.com"
    },
    "license": {
      "name": "仅供个人学习试听自用，请尊重各平台版权",
      "url": "https://aisg.highzo.top/llms.txt"
    }
  },
  "servers": [
    { "url": "https://aisg.highzo.top", "description": "生产环境（HTTPS）" }
  ],
  "tags": [
    { "name": "search", "description": "聚合搜索" },
    { "name": "chart", "description": "一键榜单" },
    { "name": "play", "description": "播放与下载" }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "tags": ["search"],
        "summary": "聚合搜索歌曲（五音源并发）",
        "operationId": "searchSongs",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" }, "description": "歌名或歌手，支持中英文", "example": "周杰伦" },
          { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "每个音源的条数（不是总数）。多源聚合后 data.list 总数可达 size × 5；配合 source 参数可精确控制返回量。" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "页码" },
          { "name": "source", "in": "query", "schema": { "type": "string", "enum": ["kuwo", "kugou", "netease", "itunes", "audius"] }, "description": "限定音源，留空则聚合全部" }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "list": [
                      {
                        "id": "kuwo:474678847",
                        "title": "花海",
                        "artist": "周杰伦",
                        "album": "",
                        "source": "kuwo",
                        "duration": 210,
                        "cover": "https://img1.kuwo.cn/star/albumcover/474678847.jpg",
                        "ext": "mp3"
                      }
                    ],
                    "total": 20
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/charts": {
      "get": {
        "tags": ["chart"],
        "summary": "一键榜单目录（4 组约 71 个榜单）",
        "operationId": "listCharts",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "groups": [
                      {
                        "name": "年龄 / 年代",
                        "charts": [
                          { "id": "49223", "name": "90后热歌榜", "intro": "90 后最爱，按年龄段喜爱热度排序（酷狗官方榜）", "kind": "kugou" }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/chart": {
      "get": {
        "tags": ["chart"],
        "summary": "拉取整张榜单歌曲（默认已做可播性预解析，返回列表基本都能直接播）",
        "operationId": "getChart",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "榜单 ID。酷狗官方榜用数字（49223=90后、49225=80后、49224=00后、8888=TOP500、6666=飙升榜、74534=新歌榜、4681=欧美、4680=Billboard、4673=日本公信榜、38623=韩国Melon）；年份榜用 y+年份（y2026、y2025、y2024、y2002）", "example": "49223" },
          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "拉取首数" },
          { "name": "playable", "in": "query", "schema": { "type": "string", "enum": ["0", "1"], "default": "1" }, "description": "是否做可播性预解析，传 0 关闭以加快返回" }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "list": [
                      { "id": "kuwo:123456", "title": "示例歌曲", "artist": "示例歌手", "source": "kuwo", "duration": 240, "cover": "", "ext": "mp3" }
                    ],
                    "name": "90后热歌榜",
                    "intro": "90 后最爱",
                    "source": "kugou",
                    "playable": { "total": 50, "direct": 20, "swapped": 27, "failed": 3, "skipped": 0 }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/song/url": {
      "get": {
        "tags": ["play"],
        "summary": "获取歌曲播放地址",
        "operationId": "getSongUrl",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "歌曲 ID，形如 kuwo:474678847", "example": "kuwo:474678847" }
        ],
        "responses": {
          "200": {
            "description": "成功；code=1001 需会员或版权受限，code=1004 音源限流",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": { "code": 0, "msg": "ok", "data": { "url": "https://...", "source": "kuwo", "br": 128 } }
              }
            }
          }
        }
      }
    },
    "/api/play": {
      "get": {
        "tags": ["play"],
        "summary": "音频流代理，支持 Range，可直接作为 audio 标签的 src",
        "operationId": "playStream",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "kuwo:474678847" }
        ],
        "responses": {
          "200": { "description": "音频流（audio/mpeg）" },
          "206": { "description": "分段音频流（Range 请求）" },
          "502": { "description": "取流失败（需会员或版权受限）" },
          "503": { "description": "音源限流" }
        }
      }
    },
    "/api/download": {
      "get": {
        "tags": ["play"],
        "summary": "下载 MP3 到本地，带 Content-Disposition 附件头",
        "operationId": "downloadSong",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "kuwo:474678847" },
          { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "文件名（不含扩展名）", "example": "花海" }
        ],
        "responses": {
          "200": { "description": "音频文件附件" }
        }
      }
    },
    "/api/alt": {
      "get": {
        "tags": ["search"],
        "summary": "自动换源：原版本放不了时，在其它音源找同名可播版本",
        "operationId": "findAlternative",
        "parameters": [
          { "name": "title", "in": "query", "required": true, "schema": { "type": "string" }, "example": "晴天" },
          { "name": "artist", "in": "query", "schema": { "type": "string" }, "example": "周杰伦" },
          { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "原歌曲 ID（可选，用于排除自身）" }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": { "code": 0, "msg": "ok", "data": { "song": { "id": "kuwo:123", "title": "晴天", "artist": "周杰伦", "source": "kuwo" }, "url": { "url": "https://...", "source": "kuwo", "br": 128 } } }
              }
            }
          }
        }
      }
    },
    "/api/sources": {
      "get": {
        "tags": ["search"],
        "summary": "音源列表",
        "operationId": "listSources",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Response" },
                "example": { "code": 0, "msg": "ok", "data": { "list": [{ "name": "kuwo", "label": "酷我" }, { "name": "kugou", "label": "酷狗" }, { "name": "netease", "label": "网易云" }, { "name": "itunes", "label": "iTunes" }, { "name": "audius", "label": "Audius" }] } }
              }
            }
          }
        }
      }
    },
    "/api/rank/list": {
      "get": {
        "tags": ["chart"],
        "summary": "酷狗官方排行榜列表",
        "operationId": "listRanks",
        "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }
      }
    },
    "/api/rank/songs": {
      "get": {
        "tags": ["chart"],
        "summary": "酷狗官方榜单歌曲（分页，默认已做可播性预解析）",
        "operationId": "getRankSongs",
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer", "default": 8888 }, "description": "榜单 ID，默认 8888 TOP500" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 30 } },
          { "name": "playable", "in": "query", "schema": { "type": "string", "enum": ["0", "1"], "default": "1" } }
        ],
        "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }
      }
    },
    "/healthz": {
      "get": {
        "summary": "健康检查",
        "operationId": "health",
        "responses": { "200": { "description": "返回纯文本 ok", "content": { "text/plain": { "example": "ok" } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Response": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "description": "0 成功；1001 需会员或版权受限；1004 音源限流；其它非 0 为失败" },
          "msg": { "type": "string" },
          "data": { "type": "object" }
        }
      },
      "Song": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "kuwo:数字 / kugou:HASH / netease:数字 / itunes:数字 / audius:短ID" },
          "title": { "type": "string" },
          "artist": { "type": "string" },
          "album": { "type": "string" },
          "source": { "type": "string", "enum": ["kuwo", "kugou", "netease", "itunes", "audius"] },
          "duration": { "type": "integer", "description": "时长（秒）" },
          "cover": { "type": "string" },
          "ext": { "type": "string", "example": "mp3" }
        }
      }
    }
  }
}