ASIN 分析 API

鉴权与积分

基础分析8分，可选采集和AI配置各1分，全选20分。初始100永久积分；无每日任务次数上限。会员及完整积分规则。usage.balance / temporary / permanent 为精确十进制字符串，分别代表可用、有期限、永久积分；任务 billing 返回扣分和退款明细。失败/超时全额返还积分；过期订阅积分退入24小时补偿批次，到期剩余再按20%转存。

API Key 在“个人中心 → API 设置”中管理：创建即生效，无需启用操作。每个用户只能拥有一个 Key；若 Key 泄露，可点击“重新生成”，旧 Key 立即失效。普通业务接口支持以下任一 Header，推荐 Bearer：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

# 等价写法
X-API-Key: YOUR_API_KEY

每个已鉴权 JSON 响应都会附带以下公共字段：

{
  "usage": {
    "used": "20",
    "limit": "100",
    "remaining": "80",
    "is_unlimited": false
  },
  "api_request_count": 18
}

文件直链通过短期 ticket 查询参数鉴权，二进制响应通过 X-Usage-* 与 X-API-Request-Count Header 返回用量信息。

接口约定

提交任务

每次提交一个 ASIN，成功返回 HTTP 202 与任务 ID。处理服务器维护时任务状态为 waiting，恢复后会自动执行。

curl -X POST "https://cy126.com/openapi/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asin": "B0XXXXXXXX",
    "site": "US",
    "collection_config": {
      "bullet_points": true,
      "reviews": true,
      "ad_difficulty": false
    },
    "ai_analysis": {
      "basic": true,
      "ad_strategy": true,
      "product_selection": false,
      "visual": false,
      "inventory": false,
      "copy": true,
      "development": false,
      "pricing": false,
      "weakness": false,
      "strategy": false
    }
    }'

请求参数

响应字段（HTTP 202）

响应示例

{
  "success": true,
  "message": "任务已提交",
  "task": {
    "task_id": "a1b2c3d4e5f6",
    "asin": "B0XXXXXXXX",
    "site": "US",
    "source": "api",
    "status": "queued",
    "status_text": "排队中",
    "stage": null,
    "terminal": false,
    "archived": false,
    "submitted_at": "2026-08-20 10:00:00",
    "completed_at": null,
    "error": null,
    "file_available": false,
    "file_info_url": null,
    "collection_config": { "bullet_points": true, "reviews": true, "ad_difficulty": false },
    "ai_analysis": { "basic": true, "ad_strategy": true, "product_selection": false, "visual": false,
                     "inventory": false, "copy": true, "development": false, "pricing": false,
                     "weakness": false, "strategy": false }
  },
  "duration_notice": "任务通常需要 30-60 分钟，也可能因队列繁忙而更久；建议每 5 分钟轮询一次状态",
  "usage": { "used": "20", "limit": "100", "remaining": "80" },
  "api_request_count": 19
}

批量提交任务

API 单次最多提交 10 个任务；网页任务中心每次提交单个 ASIN。每个元素的字段与「提交任务」完全一致（site 必填，基础分析自动执行）。任一元素校验失败则整批拒绝（不会部分创建）；积分按每个任务的勾选配置合计，整批原子扣分。个别任务被处理服务器拒绝时，会出现在响应的 failed 数组中，其余任务正常受理。

curl -X POST "https://cy126.com/openapi/v1/tasks/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {
        "asin": "B0XXXXXXXX",
        "site": "US",
        "collection_config": { "reviews": true },
        "ai_analysis": { "basic": true, "copy": true }
      },
      {
        "asin": "B0YYYYYYYY",
        "site": "US",
        "ai_analysis": { "basic": true }
      }
    ]
  }'

请求参数

响应字段（HTTP 202）

查询单个任务

curl "https://cy126.com/openapi/v1/tasks/a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

请求参数

响应字段（HTTP 200）

任务不存在或不属于当前用户时返回 HTTP 404 task_not_found。查询到 waiting 状态的任务时，服务端会自动尝试唤醒等待队列。

查询当前用户的全部任务

返回通过 Web 与 API 提交的所有任务，包括已归档任务，适合 Agent 恢复上下文和批量检查进度。

curl "https://cy126.com/openapi/v1/tasks?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 可选筛选
?status=running
?source=api
?status=success&source=web

请求参数

响应字段（HTTP 200）

status / source 传入非法值时分别返回 invalid_status / invalid_source；page / page_size 非整数时返回 invalid_pagination（HTTP 400）。

下载最终 XLSX

下载任务生成的最终 XLSX 文件。先获取文件信息及可直接访问的 download_url，再请求该地址保存文件；XLSX 中包含数据表、AI 分析及任务生成的全部产物。

# 第一步：获取文件信息
curl "https://cy126.com/openapi/v1/tasks/a1b2c3d4e5f6/file" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 第二步：直接请求响应中的完整 download_url
curl -L "DOWNLOAD_URL_FROM_RESPONSE" -o result.xlsx

请求参数

响应（HTTP 200）

响应示例

{
  "success": true,
  "file": {
    "task_id": "a1b2c3d4e5f6",
    "filename": "B0XXXXXXXX-US-分析结果.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 428617,
    "download_url": "https://cy126.com/openapi/v1/tasks/a1b2c3d4e5f6/file/download?ticket=SHORT_LIVED_TICKET",
    "auth_method": "signed_ticket",
    "expires_at": "2026-09-07T00:05:00Z"
  },
  "usage": { "used": "20", "limit": "100", "remaining": "80", "is_unlimited": false },
  "api_request_count": 20
}

任务未完成时返回 HTTP 409 task_not_ready，请继续每 5 分钟轮询一次状态，待 status=success 后再下载，不要重复提交同一任务；任务不存在返回 404 task_not_found；文件丢失返回 404 file_not_found。

任务状态机

status 字段的全部取值及流转规则如下；status_text 为对应的实际状态文案（running 状态会按服务端队列细分为 获取中 / 分析中 / 待分析，与 Web 端显示一致）。

Python / Agent 完整流程

import time
import requests

BASE_URL = "https://cy126.com/openapi/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

created = requests.post(
    f"{BASE_URL}/tasks",
    headers=HEADERS,
    json={
        "asin": "B0XXXXXXXX",
        "site": "US",
        "collection_config": {"reviews": True},
        "ai_analysis": {"basic": True, "copy": True},
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["task"]["task_id"]

# 建议每 5 分钟轮询一次状态，先确认状态再决定下载或重提
while True:
    response = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
    response.raise_for_status()
    task = response.json()["task"]
    if task["status"] == "success":
        break
    if task["terminal"]:
        # failed / timeout：读取 error 后直接重新提交任务即可
        raise RuntimeError(task.get("error") or task["status"])
    time.sleep(300)

file_info_response = requests.get(
    f"{BASE_URL}/tasks/{task_id}/file",
    headers=HEADERS,
    timeout=30,
)
file_info_response.raise_for_status()
file_info = file_info_response.json()["file"]

# download_url 已包含短期 ticket，请在 5 分钟内下载；不要记录完整 URL
file_response = requests.get(file_info["download_url"], timeout=120)
file_response.raise_for_status()
with open(f"{task_id}.xlsx", "wb") as output:
    output.write(file_response.content)

print("usage:", file_response.headers.get("X-Usage-Used"))

Agent 调用文档

这是一份平台无关的 Markdown 文档，包含全部接口、参数、状态、错误码、安全约束和完整调用流程。可以直接将文档提交给 Agent、AI 助手或 vibe coding 工具，让其按文档调用 API。

交付前检查

1. 1

   选择在线查看，或下载完整的 agent-api-guide.md 交给 Agent。

2. 2

   准备当前用户的 API Key 与 ASIN；优先通过环境变量或 Secret 功能提供 Key。

3. 3

   确认 Agent 能执行后台轮询与完成通知，再按文档提交任务并下载 XLSX。

4. 4

   确认 Agent 遵守对话要求：提交前用中文完整转述采集与分析配置的可选参数；基础分析必选、不让用户选择；战略可独立运行；状态用中文汇报（排队中、待分析、分析中、已完成、失败、超时）；最终输出字符串形式的完整文件路径。

常见错误码

所有错误响应均为统一结构：success=false + error.code（机器可读）+ error.message（中文说明），并同样附带 usage 与 api_request_count 公共字段（能鉴权成功时）：

{
  "success": false,
  "error": { "code": "invalid_asin", "message": "asin 必须是 10 位字母或数字" },
  "usage": { "used": "20", "limit": "100", "remaining": "80", "is_unlimited": false },
  "api_request_count": 19
}