接入嚮導

賬號與憑證

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 等會真實調用外部或產生費用/短信，調試前先確認。

常見問題