API 文档

所有技能能力都有对应的 HTTP 接口。拿 API Key 直接 POST 即可，不需要安装任何东西。

1. 拿到 API Key

两种方式，任选其一：

· 在控制台用手机号登录后创建（可创建多个，永久有效）
· 在对话里跑任意技能的 scripts/onboarding.py，注册即自动生成

新用户注册赠送 50 积分，可直接试用。少数单次消耗较高的接口需要购买套餐后使用，响应会明确告知。

2. 鉴权

把 API Key 放在 Authorization 头里。不需要 Bearer 前缀（带了也认）。

Authorization: sk-xxxxxxxxxxxx

3. 调用示例

全部接口都是 POST + JSON body。参数直接平铺在顶层。

curl

curl -X POST https://api.yasinaai.com/v2/keepa/product-finder \
  -H "Authorization: sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "com",
    "perPage": 50,
    "selection": {
      "current_SALES_lte": 50000,
      "productType": [0]
    }
  }'

Python（只用标准库）

import os, json, urllib.request

req = urllib.request.Request(
    "https://api.yasinaai.com/v2/keepa/product-finder",
    data=json.dumps({
        "domain": "com",
        "perPage": 50,
        "selection": {"current_SALES_lte": 50000, "productType": [0]},
    }).encode(),
    headers={
        "Authorization": os.environ["YASINA_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as resp:
    # 积分消耗在响应头里，不在 body
    print("扣减积分:", resp.headers["X-Credits-Cost"])
    print("剩余余额:", resp.headers["X-Credits-Balance"])
    print(json.load(resp)["data"])

4. 响应格式

统一外壳，业务数据在 data 里。

{
  "code": "OK",
  "message": "",
  "data": {
    "totalResults": 15165800,
    "page": 0,
    "returnedCount": 50,
    "asins": ["B0BBP27Y47", "B0F49G1Q89", "..."]
  },
  "requestId": "0079b341-b2a6-40cb-8ffb-f886c0015771"
}

积分信息在响应头

不放在 body 里 —— 那样每个接口的返回结构都要多包一层。

响应头	含义
`X-Credits-Cost`	本次扣减的积分
`X-Credits-Before`	调用前余额
`X-Credits-Balance`	调用后余额
`X-Request-Id`	请求 ID，排查问题时提供给客服

5. 错误处理

失败时 code 不为 OK，message 是可直接展示给用户的中文。

HTTP	code	含义
400	`INVALID_PARAM`	参数不合法。报错信息会指出哪个字段以及正确写法
400	`BUSINESS_REJECTED`	业务性拒绝，例如没有匹配结果
401	`UNAUTHORIZED`	API Key 无效或已删除
402	`INSUFFICIENT_CREDITS`	积分不足，需要充值
403	`USER_FROZEN`	账号被冻结，联系客服（重新注册没用）
429	`RATE_LIMITED`	触发限流，稍后重试
502	`UPSTREAM_ERROR`	数据源不可用。不扣积分
504	`UPSTREAM_TIMEOUT`	数据源超时。不扣积分