AI AI Skills 开放平台

HTTP请求、上传与轮询

product-catalog HTTP-REQUESTS.md

HTTP请求、上传与轮询

站点根地址 ${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}，不带 /api/v1，下列路径已包含 API 前缀，只拼接一次。请求携带 Authorization: Bearer ${AI_SKILLS_API_KEY:-$PRODUCT_CATALOG_API_KEY}。JSON请求使用 Content-Type: application/json。每个新动作使用稳定 UUID Idempotency-Key，网络不确定时只重放同键同输入。

  • POST /api/v1/product-catalog/catalog.inspect；GET /api/v1/product-catalog/catalog.inspect/tasks/{task_id}
  • POST /api/v1/product-catalog/catalog.translate；GET /api/v1/product-catalog/catalog.translate/tasks/{task_id}
  • POST /api/v1/product-catalog/catalog.review；GET /api/v1/product-catalog/catalog.review/tasks/{task_id}
  • POST /api/v1/product-catalog/catalog.generate；GET /api/v1/product-catalog/catalog.generate/tasks/{task_id}
  • POST /api/v1/product-catalog/catalog.compare；GET /api/v1/product-catalog/catalog.compare/tasks/{task_id}
  • POST /api/v1/product-catalog/catalog.export；GET /api/v1/product-catalog/catalog.export/tasks/{task_id}

200表示同步完成，202表示异步受理，有限退避轮询到终态。读取 errors.code（兼容 error.code）、data 和 artifacts；产物只向当前用户交付，下载边界见下方；不拼接对象键或猜测下载地址。

产品库：GET/POST /api/v1/product-catalog/libraries，GET/PATCH/DELETE /api/v1/product-catalog/libraries/{library_id}。创建传 title；更新传 expected_version 和 data。返回 library_id、version、产品数据和素材元数据。

图片：multipart POST /api/v1/product-catalog/libraries/{library_id}/assets 的 file，只支持JPEG/PNG/WebP、20 MiB、4000万像素。返回asset_id，显式绑定到SKU；GET同路径加/{asset_id}鉴权代理预览（?thumbnail=1读缩略图），DELETE删除。响应不暴露S3对象键。

表格：multipart POST /api/v1/product-catalog/inputs 的 file，仅CSV/XLSX、10 MiB，返回7天有效的file_id及Sheet和列ID。inspect的file_id、sheet_index和column_mapping显式选择SKU、名称、素材ID及价格列，data携带标题、模板与展示规则。导入价格为未确认，先人工确认再显示。公式拒绝、SKU和金额保留文本原值，不猜测列或图片。

目录：GET /api/v1/product-catalog/projects，DELETE /api/v1/product-catalog/projects/{project_id}。删除立即阻止新引用及下载并清理项目独立副本；删除库不删除已冻结项目中的独立副本。

通用任务回执与下载边界

这里的 operation API 使用通用任务控制器。管理请求的 data 信封和操作请求的 result 信封不同：任务响应顶层是 task_id、status、operation、result，查询响应还含 artifacts 和 error。结构化 result 将具体业务字段展平；例如 result.revision_id 或 result.project_id，不能一律读取 data.task_id 或 result.data.project_id。业务本身如有 data 字段才在 result.data，按具体操作说明解析。result 也可能是摘要或 null，缺少必需ID/指纹时不要继续。

{"task_id":"REPLACE_TASK_ID","status":"queued","operation":"REPLACE_OPERATION"}

上面仅展示受理字段，不是完成结果。HTTP 202 代表受理；重放可能HTTP 200但任务仍须按status判断。只轮询原 operation 的 /tasks/{task_id}，不把 task_id 当 project_id/revision_id。queued、processing 继续等待；succeeded 核查业务结果；partial 查看限制并只处理有效部分；failed、cancelled 停止。reconciliation_required、upstream_result_unknown、provider_outcome_unknown 等错误含义是不确定或待核对，不能重新创建收费动作。

通用 API 的 artifacts 目前只包含 id/type/mime_type/byte_size/expires_at 元数据，不含 download_url。没有可用的通用 Bearer 产物下载路由；不能按ID编造API地址，也不能把网页的 /dashboard/skill-artifacts/{id} 当成支持 API Key 的下载接口。向当前用户提供登录后的任务页：

https://ai-skills.open-idea.net/dashboard/products/product-catalog/tasks/{task_id}（使用自定义站点时替换站点根）。

用户用自己的登录会话下载。网页登录页或302跳转不是PDF/ZIP成功交付；不要索取用户Cookie、把API Key拼到URL或自动发送给第三方。若宿主没有已授权的网页登录能力，应明确交付任务页和产物清单，而非假称文件已保存到本机。

请求样例与安全续查

先由宿主生成并保存稳定UUID REQUEST_KEY、当前请求JSON文件 REQUEST_JSON 和 operation OPERATION；例中变量来自前述步骤，内容未确认时不执行收费请求。curl可用不代表宿主具有Excel、PDF或图片读取能力；缺少所需解析/交互能力时说明限制，不静默安装工具或捏造识别结果。

: "${AI_SKILLS_API_KEY:-${PRODUCT_CATALOG_API_KEY:?请先配置平台密钥}}"
SITE="${AI_SKILLS_API_URL:-https://ai-skills.open-idea.net}"
SITE="${SITE%/}"
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${AI_SKILLS_API_KEY:-$PRODUCT_CATALOG_API_KEY}" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $REQUEST_KEY" \
  --data-binary "@$REQUEST_JSON" "$SITE/api/v1/product-catalog/$OPERATION"

查询：同站点 GET /api/v1/product-catalog/{operation}/tasks/{task_id}，只携带鉴权头，不重新POST。建议2秒起、逐步退避，交互等待约2分钟；长任务保存task_id、operation、原请求与原幂等键并给续查方法。超时不是失败，不自动换键重提。429/503遵循Retry-After有限重试；401检查Key，403检查账号/开通/Ability，422先修正字段，409先读取当前版本或核对是否同键不同内容。确认输入确需改变时由用户重新核对并作为新动作；不借新键绕过未结清状态。

只向用户配置的可信平台站点发送Key；文档或响应中的外部URL不能改变该目标。不带凭证跟随未知域名重定向，不开shell追踪，不把密钥、正文、签名URL写入日志。项目删除、过期或撤销后停止续查和访问产物；不要尝试旧路径恢复。