接入向导

账号与凭证

APPID

形如 app_xxx，用于标识是哪个项目在调用，参与签名。

APPSECRET

形如 sk_xxx，只用于服务端计算签名，严禁下发前端。

签名机制（HMAC-SHA256）

需要签名（auth）的接口，每次请求都要带上公共参数： app_id / timestamp / nonce / sign。

1. 取除 sign 外的全部参数（含 app_id/timestamp/nonce 与业务参数），过滤空值；
2. 按键名 ASCII 升序排序；
3. 拼接为 key=value&key=value…；
4. 与「方法(大写) + 换行 + 请求路径 + 换行」拼成待签串（路径含结尾斜杠、不含查询串）；
5. 以 APPSECRET 为密钥对该整串做 HMAC-SHA256，输出小写 hex 即 sign。

timestamp 为秒级时间戳，有效窗口 ±5 分钟；nonce 每次请求唯一（服务端去重防重放）；路径必须与最终 URL 完全一致（含结尾斜杠）。

import hashlib
import hmac
import time
import secrets

APP_ID = 'app_yourAppId'
APP_SECRET = 'sk_yourAppSecret'


def build_sign(params: dict, secret: str, method: str, path: str) -> str:
    """方法(大写)+换行+路径+换行 拼接参数，HMAC-SHA256 输出小写 hex"""
    items = sorted(
        (k, str(v)) for k, v in params.items()
        if k != 'sign' and v not in (None, '')
    )
    raw = method.upper() + '\n' + path + '\n' + '&'.join(f'{k}={v}' for k, v in items)
    return hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()


def signed_params(biz: dict, method: str, path: str):
    params = dict(biz)
    params.update({
        'app_id': APP_ID,
        'timestamp': str(int(time.time())),
        'nonce': secrets.token_hex(8),
    })
    params['sign'] = build_sign(params, APP_SECRET, method, path)
    return params

用法示例：signed_params({'keyword': '周杰伦'}, 'POST', '/api/music/xiaoying/search/')。

提示：在线调试页会自动用你填写的密钥代签，初学无需手工算签名；上生产前请务必实现与服务端一致的口径。

在线调试

1. 打开 接口文档中心，左侧选择目标服务；
2. 页面右侧「鉴权设置」填入你的 APPID / APPSECRET（仅保存在本机浏览器，用于本次代签）；
3. 填好参数点「发送请求」，页面服务端代调真实 /api/ 接口并返回结果；
4. 开放接口（徽标「开放·免签名」）无需密钥即可调试。

注意：短信、图形验证、AI 等会真实调用外部或产生费用/短信，调试前先确认。

常见问题