{"components":{"schemas":{"APIError":{"properties":{"code":{"type":"string"},"docs_url":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"],"type":"object"},"APIResponse":{"properties":{"data":{"description":"Response data (endpoint-specific)","type":"object"},"page":{"type":"integer"},"page_size":{"type":"integer"},"request_id":{"type":"string"},"total":{"description":"Total count (list endpoints)","type":"integer"},"usage":{"$ref":"#/components/schemas/UsageInfo"},"warnings":{"items":{"type":"string"},"type":"array"}},"required":["data","request_id"],"type":"object"},"UsageInfo":{"properties":{"credits_balance":{"description":"Remaining credits balance after this request","type":"integer"},"credits_cost":{"description":"Credits consumed for this request","type":"integer"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"info@chuhaijiang.com","name":"出海匠"},"description":"出海匠开放平台 API，提供数据查询、内容制作、社媒管理、广告营销等能力。\n\n## 认证\n\n所有请求需在 Header 中携带 `X-API-Key` 或 `Authorization: Bearer \u003cAPI-Key\u003e`。\n\n## 平台通用错误码基线\n\n以下错误由开放平台统一产生。具体接口声明的业务错误以该接口的 Responses 为准。\n\n| HTTP | Code | 说明 |\n|------|------|------|\n| 400 | BAD_REQUEST | 请求格式错误 |\n| 400 | INVALID_PARAM | 参数无效 |\n| 400 | MISSING_PARAM | 缺少必填参数 |\n| 400 | INVALID_SORT_FIELD | 排序字段不合法 |\n| 400 | INVALID_INCLUDE | include 参数不合法 |\n| 400 | PAGE_SIZE_EXCEEDED | 分页大小超限 |\n| 401 | AUTH_MISSING_KEY | 缺少 API Key |\n| 401 | AUTH_INVALID_KEY | API Key 无效 |\n| 401 | AUTH_KEY_REVOKED | API Key 已吊销 |\n| 401 | AUTH_KEY_SUSPENDED | API Key 已暂停 |\n| 402 | INSUFFICIENT_CREDITS | credits 余额不足 |\n| 403 | FORBIDDEN_SCOPE | 无权限访问此接口 |\n| 404 | ROUTE_NOT_FOUND | 接口不存在 |\n| 404 | TASK_NOT_FOUND | 异步任务不存在 |\n| 429 | RATE_LIMITED | 请求频率超限 |\n| 429 | QUOTA_EXCEEDED | 配额超限 |\n| 500 | INTERNAL_ERROR | 内部错误 |\n| 502 | BACKEND_ERROR | 后端服务错误 |\n| 503 | BACKEND_UNAVAILABLE | 后端服务不可用 |\n| 504 | BACKEND_TIMEOUT | 后端服务超时 |","title":"出海匠开放平台 API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/open/v1/ad-creatives/{id}":{"get":{"description":"获取 TikTok 广告素材详情","operationId":"chuhaijiang-ad-creative-detail","parameters":[{"description":"广告素材ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"地区代码","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","it","fr","de","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"包含的子资源，逗号分隔：calendar,core,trend,products,similar","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: core(核心指标)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ad_cover":{"description":"广告封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"ad_create_time":{"description":"广告创建时间","type":"integer"},"ad_title":{"description":"广告标题","type":"string"},"ad_url":{"description":"广告链接","type":"string"},"advertiser_avatar":{"description":"广告主头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"advertiser_id":{"description":"广告主ID","type":"string"},"advertiser_name":{"description":"广告主名称","type":"string"},"button_text":{"description":"按钮文案","type":"string"},"create_time":{"description":"创建时间(ms时间戳)","type":"integer"},"duration":{"description":"时长(ms)","type":"integer"},"id":{"description":"唯一标识","type":"string"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"web_url":{"description":"商品页面链接","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok广告素材详情","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ad-creatives/{id}/products":{"get":{"description":"获取该 TikTok 广告素材推广/关联的商品列表，含商品基本信息，用于分析这条广告在带什么货。","operationId":"chuhaijiang-ad-creative-products","parameters":[{"description":"广告素材ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_ads_detail_product_country_code":{"description":"国家代码","type":"string"},"tiktok_ads_detail_product_id":{"description":"唯一标识","type":"string"},"tiktok_ads_detail_product_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"tiktok_ads_detail_product_total_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_ads_detail_product_total_sold_count":{"description":"总销售量","type":"integer"},"tiktok_ads_detail_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_ads_detail_video_30d_sold_count":{"description":"近30天视频带货销量","type":"integer"},"tiktok_ads_detail_video_id":{"description":"视频ID","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"佣金率","type":"number"},"tiktok_product_detail_floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"一级类目","type":"string"},"tiktok_product_detail_l2_category":{"description":"二级类目","type":"string"},"tiktok_product_detail_l3_category":{"description":"三级类目","type":"string"},"tiktok_product_detail_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"商品名称","type":"string"},"tiktok_product_detail_product_rating":{"description":"商品评分(0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU属性","items":{"properties":{"has_image":{"description":"是否有图片","type":"boolean"},"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名","type":"string"},"sale_prop_values":{"description":"属性值列表","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU列表","items":{"properties":{"is_hot":{"description":"是否热销","type":"boolean"},"price":{"properties":{"discount":{"description":"折扣信息","type":"string"},"original_price":{"description":"原价","type":"string"},"original_price_value":{"description":"原价数值","type":"string"},"real_price":{"description":"实际价格","type":"number"},"unit_price_desc":{"description":"单价描述","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"属性值ID组合","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU属性","items":{"properties":{"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名(如Color)","type":"string"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"状态(1=在售)","type":"integer"},"stock":{"description":"库存","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"商品状态","type":"integer"},"tiktok_product_detail_region":{"description":"地区代码","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告关联商品","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ad-creatives/{id}/similar":{"get":{"description":"获取与该 TikTok 广告素材相似的其他广告列表，用于竞品与同类爆款调研。","operationId":"chuhaijiang-ad-creative-similar","parameters":[{"description":"广告素材ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_ads_detail_similar_ad_cover":{"description":"广告封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_ads_detail_similar_ad_create_time":{"description":"广告创建时间","type":"integer"},"tiktok_ads_detail_similar_ad_day_count":{"description":"投放天数","type":"integer"},"tiktok_ads_detail_similar_ad_title":{"description":"广告标题","type":"string"},"tiktok_ads_detail_similar_ad_type":{"description":"广告类型","type":"integer"},"tiktok_ads_detail_similar_ad_url":{"description":"广告链接","type":"string"},"tiktok_ads_detail_similar_advertiser_avatar":{"description":"广告主头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_ads_detail_similar_advertiser_id":{"description":"广告主ID","type":"string"},"tiktok_ads_detail_similar_advertiser_name":{"description":"广告主名称","type":"string"},"tiktok_ads_detail_similar_button_text":{"description":"按钮文案","type":"string"},"tiktok_ads_detail_similar_country_code":{"description":"国家代码","type":"string"},"tiktok_ads_detail_similar_creative_id":{"description":"创意ID","type":"string"},"tiktok_ads_detail_similar_duration":{"description":"时长(ms)","type":"integer"},"tiktok_ads_detail_similar_last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"tiktok_ads_detail_similar_objective_type":{"description":"投放目标类型","type":"integer"},"tiktok_ads_detail_similar_product_id":{"description":"商品ID","type":"string"},"tiktok_ads_detail_similar_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_ads_detail_similar_product_l1_category":{"description":"商品一级类目","type":"string"},"tiktok_ads_detail_similar_product_l2_category":{"description":"商品二级类目","type":"string"},"tiktok_ads_detail_similar_product_l3_category":{"description":"商品三级类目","type":"string"},"tiktok_ads_detail_similar_product_title":{"description":"商品标题","type":"string"},"tiktok_ads_detail_similar_total_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_ads_detail_similar_video_id":{"description":"视频ID","type":"string"},"tiktok_ads_detail_similar_video_play_count":{"description":"播放量","type":"integer"},"tiktok_ads_detail_similar_video_popularity":{"description":"视频热度","type":"integer"},"tiktok_ads_detail_similar_web_url":{"description":"商品链接","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"相似广告","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/accounts":{"post":{"description":"获取广告账户列表，支持按平台类型筛选，返回账户信息及统计数据\n\n绑定账户请前往出海匠进行绑定","operationId":"chuhaijiang-ads-account-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"page":{"description":"页码","type":"integer"},"page_size":{"default":10,"description":"每页条数，默认10，最大100","maximum":100,"type":"integer"},"platforms":{"description":"平台类型列表，默认 [\"tiktok-advertiser\"]","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"账号列表","items":{"properties":{"account_id":{"description":"账号ID","type":"string"},"advertiser_id":{"description":"广告主ID","type":"string"},"advertiser_name":{"description":"广告主名称","type":"string"},"platform":{"description":"平台类型","type":"string"},"remark":{"description":"备注","type":"string"},"status":{"description":"状态","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_number":{"type":"integer"},"total_page":{"type":"integer"}},"type":"object"},"stats":{"description":"账户统计信息","type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告账户列表","tags":["广告营销/1.广告账户"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/gmv-max/campaigns":{"post":{"description":"获取 GMV MAX 半托管投放系列列表，含成交额(gross_revenue)/ROAS/订单等效果指标，支持按广告户或店铺维度筛选。注意 store_ids/campaign_ids 需传 JSON 数组字符串（如 \"[\\\"id1\\\",\\\"id2\\\"]\"）。广告户/店铺需先在出海匠绑定。","operationId":"chuhaijiang-ads-gmvmax-campaigns","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（可选，不传按当前用户权限范围返回）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID（按店铺维度查时可不传）","type":"string"},"campaign_ids":{"description":"系列ID列表，JSON 数组字符串","type":"string"},"campaign_name":{"description":"系列名称模糊搜索","type":"string"},"end_date":{"description":"效果指标统计截止日 YYYY-MM-DD","type":"string"},"gmv_max_promotion_types":{"description":"GMV MAX 推广类型筛选","type":"string"},"page":{"default":1,"description":"页码，默认1","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"primary_status":{"description":"主要状态筛选","type":"string"},"start_date":{"description":"效果指标统计起始日 YYYY-MM-DD","type":"string"},"store_ids":{"description":"店铺ID列表，JSON 数组字符串，如 \"[\\\"store1\\\"]\"","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"GMV MAX 系列列表","items":{"properties":{"advertiser_id":{"description":"广告户ID","type":"string"},"campaign_id":{"description":"系列ID","type":"string"},"campaign_name":{"description":"系列名称","type":"string"},"cpa":{"description":"转化成本 CPA","type":"number"},"create_time":{"description":"创建时间","type":"string"},"currency":{"description":"货币代码","type":"string"},"gross_revenue":{"description":"成交额（GMV MAX gross_revenue）","type":"number"},"modify_time":{"description":"修改时间","type":"string"},"objective_type":{"description":"推广目标","type":"string"},"operation_status":{"description":"开关位：ENABLE / DISABLE / DELETE","type":"string"},"orders":{"description":"订单数","type":"integer"},"promotion_type":{"description":"推广类型：PRODUCT_GMV_MAX 商品 / LIVE_GMV_MAX 直播（缓存列表可能为空）","type":"string"},"report_date":{"description":"报表日期 YYYY-MM-DD","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"真实投放状态（枚举同广告系列）","type":"string"},"spend":{"description":"消耗金额","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX 系列列表","tags":["广告营销/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/gmv-max/report/campaign":{"post":{"description":"按维度+指标查询 GMV MAX 系列级报表数据，支持 campaign_id/item_group_id/item_id/stat_time_day 维度聚合与自定义指标。account_id/advertiser_id/dimensions/metrics/start_date/end_date/store_ids 均为必填。store_ids 为真数组（非字符串）。广告户/店铺需先在出海匠绑定。","operationId":"chuhaijiang-ads-gmvmax-report-campaign","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（必填）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID（必填）","type":"string"},"campaign_ids":{"description":"按系列过滤","items":{"type":"string"},"type":"array"},"dimensions":{"description":"聚合维度（必填）：campaign_id / item_group_id / item_id / stat_time_day","items":{"type":"string"},"type":"array"},"end_date":{"description":"统计截止日 YYYY-MM-DD（必填）","type":"string"},"gmv_max_promotion_type":{"description":"推广类型：PRODUCT / LIVE","type":"string"},"item_group_ids":{"description":"按商品组过滤","items":{"type":"string"},"type":"array"},"metrics":{"description":"指标列表（必填）","items":{"type":"string"},"type":"array"},"page":{"description":"页码","type":"integer"},"page_size":{"description":"每页条数，最大1000","maximum":1000,"type":"integer"},"start_date":{"description":"统计起始日 YYYY-MM-DD（必填）","type":"string"},"store_ids":{"description":"店铺ID列表（必填，真数组）","items":{"type":"string"},"type":"array"}},"required":["account_id","advertiser_id","dimensions","metrics","start_date","end_date","store_ids"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"list":{"description":"系列级报表数据","items":{"properties":{"average_video_play":{"description":"平均播放时长","type":"string"},"campaign_id":{"description":"维度：系列ID","type":"string"},"cost":{"description":"消耗金额","type":"string"},"cost_per_order":{"description":"单均成本","type":"string"},"currency":{"description":"货币代码","type":"string"},"delivery_status":{"description":"投放状态","type":"string"},"gross_revenue":{"description":"成交额（GMV MAX 系列级正确指标名）","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"item_group_id":{"description":"维度：商品组ID","type":"string"},"item_id":{"description":"维度：商品ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_clicks":{"description":"商品点击数","type":"string"},"product_impressions":{"description":"商品展示数","type":"string"},"roi":{"description":"ROI","type":"string"},"stat_time_day":{"description":"维度：统计日","type":"string"},"title":{"description":"标题","type":"string"},"tt_account_name":{"description":"TikTok 账号名","type":"string"},"video_views_p100":{"description":"100% 完播数","type":"string"},"video_views_p25":{"description":"25% 完播数","type":"string"},"video_views_p50":{"description":"50% 完播数","type":"string"},"video_views_p75":{"description":"75% 完播数","type":"string"},"video_watched_2s":{"description":"2秒播放数","type":"string"},"video_watched_6s":{"description":"6秒播放数","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX 系列报表","tags":["广告营销/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/gmv-max/report/creative":{"post":{"description":"查询 GMV MAX 素材(创意)级报表数据，含广告点击率/转化率/Hook率(2秒播放率)/完播率等素材表现指标。account_id/advertiser_id/start_date/end_date/store_ids/item_group_ids 均为必填（store_ids/item_group_ids 为真数组），无需传 dimensions/metrics。广告户/店铺需先在出海匠绑定。","operationId":"chuhaijiang-ads-gmvmax-report-creative","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（必填）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID（必填）","type":"string"},"campaign_ids":{"description":"按系列过滤","items":{"type":"string"},"type":"array"},"end_date":{"description":"统计截止日 YYYY-MM-DD（必填）","type":"string"},"gmv_max_promotion_type":{"description":"推广类型：PRODUCT / LIVE","type":"string"},"item_group_ids":{"description":"商品组ID列表（必填，真数组）","items":{"type":"string"},"type":"array"},"page":{"description":"页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"start_date":{"description":"统计起始日 YYYY-MM-DD（必填）","type":"string"},"store_ids":{"description":"店铺ID列表（必填，真数组）","items":{"type":"string"},"type":"array"}},"required":["account_id","advertiser_id","start_date","end_date","store_ids","item_group_ids"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"list":{"description":"素材级报表数据","items":{"properties":{"ad_click_rate":{"description":"广告点击率（素材级真实 CTR）","type":"string"},"ad_conversion_rate":{"description":"广告转化率（真实 CVR）","type":"string"},"ad_video_view_rate_2s":{"description":"2秒播放率（Hook 率）","type":"string"},"ad_video_view_rate_6s":{"description":"6秒播放率","type":"string"},"ad_video_view_rate_p100":{"description":"100% 完播率","type":"string"},"ad_video_view_rate_p25":{"description":"25% 完播率","type":"string"},"ad_video_view_rate_p50":{"description":"50% 完播率","type":"string"},"ad_video_view_rate_p75":{"description":"75% 完播率","type":"string"},"cost":{"description":"消耗金额","type":"string"},"creative_delivery_status":{"description":"素材投放状态","type":"string"},"currency":{"description":"货币代码","type":"string"},"gross_revenue":{"description":"成交额","type":"string"},"item_id":{"description":"维度：素材/商品ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_click_rate":{"description":"商品点击率","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"店铺内容类型","type":"string"},"title":{"description":"素材标题","type":"string"},"tt_account_authorization_type":{"description":"素材来源：AFFILIATE/AUTH_CODE 达人 / TTS_TT/TT_USER 自营 / BC_AUTH_TT BC授权","type":"string"},"tt_account_name":{"description":"TikTok 账号名","type":"string"},"tt_account_profile_image_url":{"description":"TikTok 账号头像URL","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GMV MAX 素材报表","tags":["广告营销/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/gmv-max/stores":{"post":{"description":"获取当前广告户下的 TikTok Shop 店铺列表。传 is_gmv_max=true 只返回可用于投 GMV MAX 的店铺，不传或 false 返回全部店铺。account_id 必填，可用「广告账户列表」查到。店铺需先在出海匠绑定。","operationId":"chuhaijiang-ads-gmvmax-stores","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（必填，用于数据权限过滤）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID（可选，不传则返回该账号下有 GMV Max 系列的店铺）","type":"string"},"is_gmv_max":{"description":"是否仅返回可用于投 GMV MAX 的店铺；true=只看可投的，不传或 false=全部店铺","type":"boolean"}},"required":["account_id"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"店铺列表","items":{"properties":{"account_id":{"description":"该店所属系统内部账号ID","type":"string"},"advertiser_id":{"description":"该店 GMV Max 授权所属广告户","type":"string"},"is_gmv_max_available":{"description":"是否可用于投 GMV MAX","type":"boolean"},"is_owner_bc":{"description":"是否为所有者 BC","type":"boolean"},"store_authorized_bc_id":{"description":"店铺授权的 BC ID","type":"string"},"store_code":{"description":"店铺编码","type":"string"},"store_id":{"description":"店铺ID","type":"string"},"store_name":{"description":"店铺名称","type":"string"},"store_role":{"description":"店铺角色","type":"string"},"store_status":{"description":"店铺状态","type":"string"},"targeting_region_codes":{"description":"可投放地区代码","items":{"type":"string"},"type":"array"},"thumbnail_signed_url":{"description":"店铺缩略图（S3 签名URL）","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺列表","tags":["广告营销/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/gmv-max/stores/products":{"post":{"description":"获取指定 TikTok Shop 店铺内的商品(SPU)列表，含价格区间、历史销量、GMV MAX 广告状态、可售状态。account_id 与 store_id 必填，store_id 可用「店铺列表」查到。店铺需先在出海匠绑定。","operationId":"chuhaijiang-ads-gmvmax-store-products","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（必填，用于数据权限过滤）","type":"string"},"keyword":{"description":"商品名称关键词搜索","type":"string"},"page":{"default":1,"description":"页码，默认1","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"store_id":{"description":"店铺ID（必填）","type":"string"}},"required":["account_id","store_id"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"店内商品列表","items":{"properties":{"currency":{"description":"货币代码（USD/THB 等）","type":"string"},"gmv_max_ads_status":{"description":"该商品的 GMV MAX 广告状态","type":"string"},"historical_sales":{"description":"历史销量","type":"integer"},"is_running_custom_shop_ads":{"description":"是否在跑自定义店铺广告","type":"boolean"},"item_group_id":{"description":"商品组ID（SPU ID）","type":"string"},"max_price":{"description":"最高价","type":"string"},"min_price":{"description":"最低价（SPU 下多 SKU 的价格区间下界）","type":"string"},"product_image_signed_url":{"description":"商品图片（S3 签名URL）","type":"string"},"product_name":{"description":"商品名称","type":"string"},"status":{"description":"TikTok Shop 可售状态：AVAILABLE / NOT_AVAILABLE","type":"string"},"store_id":{"description":"店铺ID","type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店内商品列表","tags":["广告营销/3.GMV MAX"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/search":{"get":{"description":"搜索 TikTok 广告素材，支持投放天数、预估GMV、互动率等过滤","operationId":"chuhaijiang-ads-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"广告分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"广告类型：1=TikTok Shop, 2=独立站, 3=应用, 4=游戏, 5=品牌, 6=线索, 7=互动","example":"spark","in":"query","name":"ad_type","required":false,"schema":{"type":"string"}},{"description":"排除Spark Ads","example":false,"in":"query","name":"exclude_spark_ads","required":false,"schema":{"type":"boolean"}},{"description":"最低播放量","example":1000,"in":"query","name":"min_views","required":false,"schema":{"type":"number"}},{"description":"最高播放量","example":1000000,"in":"query","name":"max_views","required":false,"schema":{"type":"number"}},{"description":"最低GMV（美元）","example":1000,"in":"query","name":"min_gmv","required":false,"schema":{"type":"number"}},{"description":"最高GMV（美元）","example":100000,"in":"query","name":"max_gmv","required":false,"schema":{"type":"number"}},{"description":"最少投放天数","example":1,"in":"query","name":"min_days","required":false,"schema":{"type":"number"}},{"description":"最多投放天数","example":30,"in":"query","name":"max_days","required":false,"schema":{"type":"number"}},{"description":"排序，格式: field:asc|desc。支持: cost, days, engagement, gmv, views。默认: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["cost","days","engagement","gmv","views"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ad_create_time":{"description":"广告创建时间","type":"integer"},"ad_day_count":{"description":"投放天数","type":"integer"},"ad_maximum_cost":{"description":"广告最大花费","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"ad_roas":{"description":"广告ROAS(投入产出比)","type":"number"},"ad_title":{"description":"广告标题","type":"string"},"ad_url":{"description":"广告链接","type":"string"},"advertiser_id":{"description":"广告主ID","type":"string"},"advertiser_name":{"description":"广告主名称","type":"string"},"advertiser_url":{"description":"广告主链接","type":"string"},"button_text":{"description":"按钮文案","type":"string"},"country_code":{"description":"国家代码","type":"string"},"create_time":{"description":"创建时间(ms时间戳)","type":"integer"},"duration":{"description":"时长(ms)","type":"integer"},"id":{"description":"唯一标识","type":"string"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"product_id":{"description":"商品ID","type":"string"},"product_l1_category":{"description":"商品一级类目","type":"string"},"product_l2_category":{"description":"商品二级类目","type":"string"},"product_l3_category":{"description":"商品三级类目","type":"string"},"product_title":{"description":"商品标题","type":"string"},"total_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"total_sc":{"description":"总销量","type":"integer"},"video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"video_gpm_30d":{"description":"近30天视频GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_id":{"description":"视频ID","type":"string"},"video_like_count":{"description":"点赞数","type":"integer"},"video_like_rate":{"description":"点赞率","type":"number"},"video_play_count":{"description":"播放量","type":"integer"},"video_popularity":{"description":"视频热度","type":"integer"},"web_url":{"description":"商品页面链接","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告搜索","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/adgroups":{"post":{"description":"获取 TikTok 广告组(AdGroup)列表，含预算、优化目标、出价、真实投放状态与花费/CTR/CPC 等效果指标，支持按广告户、所属系列、名称、日期范围筛选。广告户需先在出海匠绑定。","operationId":"chuhaijiang-ads-adgroups","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（可选，不传按当前用户权限范围返回）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID","type":"string"},"campaign_id":{"description":"筛选指定广告系列下的广告组","type":"string"},"end_date":{"description":"效果指标统计截止日 YYYY-MM-DD","type":"string"},"keyword":{"description":"广告组名称模糊搜索","type":"string"},"operation_status":{"description":"开关状态筛选：ENABLE / DISABLE","type":"string"},"page":{"default":1,"description":"页码，从1开始，默认1","type":"integer"},"page_size":{"default":20,"description":"每页条数，默认20，最大100","maximum":100,"type":"integer"},"start_date":{"description":"效果指标统计起始日 YYYY-MM-DD","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"广告组列表","items":{"properties":{"adgroup_id":{"description":"广告组ID（TikTok）","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"广告户ID","type":"string"},"bid_price":{"description":"出价金额（仅自定义出价时有效）","type":"number"},"bid_type":{"description":"出价方式：BID_TYPE_NO_BID 自动 / BID_TYPE_CUSTOM 自定义","type":"string"},"billing_event":{"description":"计费方式：CPC / CPM / CPV / OCPM","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式：BUDGET_MODE_DAY / BUDGET_MODE_TOTAL","type":"string"},"campaign_id":{"description":"所属系列ID","type":"string"},"campaign_name":{"description":"所属系列名称","type":"string"},"clicks":{"description":"点击次数","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","type":"integer"},"cost_per_conversion":{"description":"转化成本","type":"number"},"cpc":{"description":"单次点击成本","type":"number"},"cpm":{"description":"千次展示成本","type":"number"},"ctr":{"description":"点击率","type":"number"},"currency":{"description":"货币代码","type":"string"},"impressions":{"description":"展示次数","type":"integer"},"operation_status":{"description":"开关位：ENABLE / DISABLE","type":"string"},"optimization_goal":{"description":"优化目标：CLICK / CONVERT / SHOW / REACH","type":"string"},"report_date":{"description":"最近报表日 YYYY-MM-DD","type":"string"},"schedule_end_time":{"description":"投放结束时间（Unix 秒）","type":"integer"},"schedule_start_time":{"description":"投放开始时间（Unix 秒）","type":"integer"},"secondary_status":{"description":"真实投放状态：ADGROUP_STATUS_DELIVERY_OK 投放中 / _NOT_DELIVER 未投放 / _TIME_DONE 已结束 / _AUDIT 审核中 / _DISABLE 暂停 / _BALANCE_EXCEED 余额不足 等","type":"string"},"spend":{"description":"消耗金额","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告组列表","tags":["广告营销/2.常规投放"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/ads":{"post":{"description":"获取TikTok广告列表，支持字段选择、过滤条件和指标数据","operationId":"chuhaijiang-ads-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"广告主账号ID","type":"string"},"advertiser_id":{"description":"广告户ID","type":"string"},"exclude_field_types_in_response":{"description":"排除的字段类型","items":{"type":"string"},"type":"array"},"fields":{"description":"指定返回字段","items":{"type":"string"},"type":"array"},"filtering":{"description":"过滤条件（点击展开查看详细字段）","properties":{"ad_ids":{"description":"广告ID列表","items":{"type":"string"},"type":"array"},"ad_name":{"description":"广告名称（模糊搜索）","type":"string"},"adgroup_ids":{"description":"广告组ID列表","items":{"type":"string"},"type":"array"},"campaign_ids":{"description":"广告计划ID列表","items":{"type":"string"},"type":"array"},"objective_type":{"description":"投放目标类型","type":"string"},"primary_status":{"description":"主状态","type":"string"},"secondary_status":{"description":"次状态","type":"string"}},"type":"object"},"force_refresh":{"description":"是否强制刷新数据","type":"boolean"},"page":{"description":"页码","type":"integer"},"page_size":{"default":20,"description":"每页条数，默认20，最大100","maximum":100,"type":"integer"},"with_metrics":{"description":"是否包含指标数据","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"广告列表","items":{"properties":{"ad_id":{"type":"string"},"ad_name":{"type":"string"},"adgroup_id":{"type":"string"},"advertiser_id":{"type":"string"},"campaign_id":{"type":"string"},"create_time":{"type":"string"},"operation_status":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total_number":{"type":"integer"},"total_page":{"type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告列表","tags":["广告营销/2.常规投放"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/ads/detail":{"post":{"description":"获取单个TikTok广告的完整详情，包含定向配置、预算竞价、效果数据等","operationId":"chuhaijiang-ads-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ad_id":{"description":"广告ID","type":"string"}},"required":["ad_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"ad_id":{"description":"广告ID","type":"string"},"ad_name":{"description":"广告名称","type":"string"},"ad_text":{"description":"广告文案","type":"string"},"adgroup_id":{"description":"广告组ID","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"广告户ID","type":"string"},"advertiser_name":{"description":"广告户名称","type":"string"},"bid_price":{"description":"竞价","type":"number"},"budget":{"description":"预算金额","type":"number"},"campaign_id":{"description":"推广系列ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"currency":{"description":"货币类型","type":"string"},"data_items":{"description":"效果数据","items":{"type":"object"},"type":"array"},"images":{"description":"图片文件","items":{"properties":{"file_name":{"type":"string"},"url":{"type":"string"}},"type":"object"},"type":"array"},"objective_type_desc":{"description":"推广目标描述","type":"string"},"operation_status":{"description":"操作状态","type":"string"},"schedule_end_time":{"description":"投放结束时间","type":"string"},"schedule_start_time":{"description":"投放开始时间","type":"string"},"state_desc":{"description":"状态描述","type":"string"},"videos":{"description":"视频文件","items":{"properties":{"file_name":{"type":"string"},"url":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告详情","tags":["广告营销/2.常规投放"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/ads/insight":{"post":{"description":"获取TikTok广告效果数据，包含看板汇总和每日明细","operationId":"chuhaijiang-ads-insight-data","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ad_id":{"description":"广告ID","type":"string"},"end_date":{"description":"查询结束日期，格式YYYY-MM-DD，不传则查全量","type":"string"},"start_date":{"description":"查询起始日期，格式YYYY-MM-DD，不传则查全量","type":"string"}},"required":["ad_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"board_items":{"description":"看板汇总数据","items":{"properties":{"key":{"type":"string"},"label":{"type":"string"},"trend":{"type":"number"},"value":{"type":"number"}},"type":"object"},"type":"array"},"detail_items":{"description":"每日明细数据","items":{"properties":{"date":{"type":"string"},"metrics":{"type":"object"}},"type":"object"},"type":"array"},"metrics":{"description":"可用指标定义列表","items":{"properties":{"key":{"type":"string"},"label":{"type":"string"},"unit":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告数据洞察","tags":["广告营销/2.常规投放"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/campaigns":{"post":{"description":"获取 TikTok 广告系列(Campaign)列表，含预算、真实投放状态与花费/ROAS/CTR/CPC 等效果指标，支持按广告户、系列类型、名称、日期范围筛选。广告户需先在出海匠绑定，可用「广告账户列表」查到 advertiser_id。","operationId":"chuhaijiang-ads-campaigns","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"系统内部账号ID（可选，不传按当前用户权限范围返回）","type":"string"},"advertiser_id":{"description":"TikTok 广告户ID","type":"string"},"campaign_type":{"description":"系列类型：regular（常规）/ gmv_max","type":"string"},"end_date":{"description":"效果指标统计截止日 YYYY-MM-DD","type":"string"},"keyword":{"description":"系列名称模糊搜索","type":"string"},"operation_status":{"description":"开关状态筛选：ENABLE / DISABLE","type":"string"},"page":{"default":1,"description":"页码，从1开始，默认1","type":"integer"},"page_size":{"default":20,"description":"每页条数，默认20，最大100","maximum":100,"type":"integer"},"start_date":{"description":"效果指标统计起始日 YYYY-MM-DD","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"list":{"description":"广告系列列表","items":{"properties":{"advertiser_id":{"description":"广告户ID","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式：BUDGET_MODE_DAY 日预算 / BUDGET_MODE_TOTAL 总预算","type":"string"},"campaign_id":{"description":"系列ID（TikTok）","type":"string"},"campaign_name":{"description":"系列名称","type":"string"},"campaign_type":{"description":"系列类型：REGULAR / GMV_MAX","type":"string"},"clicks":{"description":"点击次数","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","type":"integer"},"cost_per_conversion":{"description":"转化成本","type":"number"},"cpa":{"description":"转化成本 CPA","type":"number"},"cpc":{"description":"单次点击成本","type":"number"},"cpm":{"description":"千次展示成本","type":"number"},"ctr":{"description":"点击率","type":"number"},"currency":{"description":"货币代码","type":"string"},"impressions":{"description":"展示次数","type":"integer"},"is_cbo":{"description":"是否开启系列预算优化 CBO","type":"boolean"},"objective_type":{"description":"推广目标，如 LEAD_GENERATION / TRAFFIC / PRODUCT_SALES","type":"string"},"offsite_project_id":{"description":"关联 Amazon 站外 Project ID（仅站外系列）","type":"integer"},"offsite_project_name":{"description":"关联站外 Project 名称","type":"string"},"operation_status":{"description":"开关位：ENABLE / DISABLE / DELETE","type":"string"},"orders":{"description":"订单数（店内购物次数）","type":"integer"},"report_date":{"description":"最近报表日 YYYY-MM-DD","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"真实投放状态（徽章以此为准）：CAMPAIGN_STATUS_ENABLE 投放中 / _DISABLE 暂停 / _BUDGET_EXCEED 预算超支 / _ADVERTISER_AUDIT_DENY 审核拒绝 等","type":"string"},"spend":{"description":"消耗金额","type":"number"},"total_onsite_shopping_amount":{"description":"店内购物总额（成交额）","type":"number"}},"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总条数","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"广告系列列表","tags":["广告营销/2.常规投放"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/agent/chat":{"post":{"description":"调用 AI 对话 Agent，返回 Server-Sent Events (SSE) 事件流。**网关入口 0 Credit**，实际按输出 token 由 agent 内部结算（见「计费」）。\n\n**协议格式** — 响应是分块 SSE 流（**不是**单一 JSON）。每个事件由 `event:` 行 + `data:` 行 + 一行空行组成，符合 SSE 标准：\n\n```text\nevent: \u003c事件类型\u003e\ndata: \u003cJSON 对象\u003e\n\n```\n\n- `data` 行是标准 JSON，非 ASCII 字符（如中文）按 `\\uXXXX` 转义；客户端逐行取 `data:` 后做 JSON 反序列化即可还原。\n- 每个事件都带自增 `seq`，客户端按 `seq` 升序处理；`content` 的文本分片尤其要按 `seq` 拼接还原完整回复。\n- 流中会穿插心跳注释行 `: ping - \u003c时间戳\u003e`（以 `:` 开头，符合 SSE 注释规范），**不是事件，直接忽略**，仅用于保活长连接。\n\n**计费** — AI 对话按 **输出 token** 计费，由 agent 内部结算（不在网关入口扣费）：\n\n| codename | 说明 | 价格（按输出 token） |\n|---|---|---|\n| `core` | 平台**默认**，综合能力更强，适合复杂任务 | 约 **¥1,250 / 1M**（¥1.25 / 1K） |\n| `aura` | 更**经济**的轻量选项，适合成本敏感场景 | 约 **¥280 / 1M** |\n\n- **只按 output token 计费；input、cache 读 / 写全部不计费。** 单价看着偏高正是因为如此——成本只折进输出：一轮对话的输入（系统提示 + 工具结果 + 历史，常达数万乃至十几万 token，且大量命中 cache）通常远多于输出，而这些**全部免费**，整体反而更省。\n- 对话中触发的视频 / 图片生成等能力，按对应异步任务规则**另行计费**。\n- 余额为 0 时**当前轮会跑完**，下一轮请求被拒绝（流内以 `event: error`、`code: INSUFFICIENT_CREDITS` 返回）。\n\n**model 参数** — 对外不透明 codename，区别在于**能力与价格**（见上表）。不传或空串 → 默认用 `core`；传非法值静默回落到 `core`，不报错。\n\n**attachments 参数** — 对象存储引用，给 agent 提供用户上传的产品图 / 模特图 / 视频。每项须含 `os_bucket` + `os_key`，仅填这两项即可让下游 image / video 生成工具按 key 索引；如需 LLM 直接 fetch（如 `recognize_image`）则填预签名 `url`（开放平台路径下需调方自己签好）。详见请求体 schema 及示例。\n\n**assistant 文本里的 XML 标签** — `content` 拼接出的完整文本除 Markdown 外还内联以下标签，且**可能跨多个 `content` 事件分片**，客户端应按 `seq` 累积完整文本后再解析：\n\n| 标签 | 形态 | 含义 |\n|---|---|---|\n| `\u003creport\u003e` | 成对 | 核心产物：分析报告，title 属性为标题，body 为标准 Markdown，建议渲染到独立面板 |\n| `\u003centity\u003e` | 自闭合 | 实体引用（商品 / 达人 / 店铺 / 视频等），type / id 等在属性里 |\n| `\u003cchart\u003e` | 成对 | 报告内图表，type（bar/line/pie）、title 属性，标签体为 JSON，数据自包含 |\n| `\u003ctask-result\u003e` | 自闭合 | 图片 / 视频生成结果，result_type（image/video）、image_url 在属性里 |\n| `\u003cvideo-scripts\u003e` | 成对 | 视频脚本方案，标签体为 JSON 数组，每项含 `scenes` |\n| `\u003cselect\u003e` | 成对 | 需用户选择的控件，始终在 `\u003c/report\u003e` 之外 |\n| `\u003csuggestions\u003e` | 成对 | 信息性后续建议（Markdown 列表），不暂停对话 |\n| `\u003cconnect\u003e` | 自闭合 | OAuth 授权按钮，platform 属性指定平台 |\n\n- `\u003creport\u003e` — 一轮通常只有一个，body 为 Markdown，提取后即可作为「报告」展示；其后的 `\u003cselect\u003e` / `\u003csuggestions\u003e` 在报告之外，需单独提取渲染。报告全文已在本轮 `content` 流中，无需另取。\n\n### 如何从流里提取报告\n\n报告全文就在 `content` 事件流里，**无需额外接口**。提取三步：\n\n1. **累积文本**：收集所有 `event: content` 的 `data.text` 拼成完整文本（content 按 `seq` 顺序推送，按到达顺序拼接即可）。\n2. **等闭合**：报告内容较长，会跨多个 `content` 分片；最简单的做法是等 `event: done` 后再一次性提取（若要边流式边渲染，则需等 `\u003c/report\u003e` 出现再算完整）。\n3. **正则提取**：取出 `\u003creport\u003e` 的标题和正文（正文为标准 Markdown，直接丢给 Markdown 渲染器即可）。\n\n```js\nlet full = \"\"\nes.addEventListener(\"content\", e =\u003e { full += JSON.parse(e.data).text })\nes.addEventListener(\"done\", () =\u003e {\n  const m = full.match(/\u003creport\\s+[^\u003e]*\u003e([\\s\\S]*?)\u003c\\/report\u003e/)\n  if (m) {\n    const title    = m[0].match(/title=\"([^\"]*)\"/)?.[1] ?? \"\"\n    const markdown = m[1].trim()   // 报告正文（Markdown）\n    renderReport(title, markdown)  // 渲染到独立面板\n  }\n}, { once: true })\n```\n\n报告正文里可能内嵌 `\u003centity\u003e` / `\u003cchart\u003e` 等标签，按上文各标签的说明二次处理；其余纯文本（`\u003creport\u003e` 之外）是对话气泡内容。\n\n报告全文从 `content` 流取（本段方法）；若只需引用本轮报告，`event: done` 的 `report_ids` 已给出持久化的报告 id，无需再从全文里解析。\n\n- `\u003cselect\u003e` — 需用户选择；出现时本轮 `event: done` 的 `stop_reason` 是 `\"awaiting_user_input\"`（而非 `\"end_turn\"`）。格式：\n\n```xml\n\u003cselect id=\"choice_xxx\" question=\"您想做什么？\" multi=\"false\"\u003e\n  \u003coption value=\"option_a\"\u003e选项 A 的展示文本\u003c/option\u003e\n  \u003coption value=\"option_b\"\u003e选项 B 的展示文本\u003c/option\u003e\n\u003c/select\u003e\n```\n\n  处理：渲染选择 UI（带 `multi=\"true\"` 属性时为多选）→ 用户选定后把所选 option 的 **`value` 属性值**（不是展示文本）作为下一条请求的 `message`（保持同一 `session_id`）回传。\n\n- `\u003csuggestions\u003e` — 信息性的后续建议（内含 Markdown 列表），**不**暂停对话（`stop_reason` 仍为 `end_turn`）。可渲染为可点击建议项，点击后把该项文本作为下一条 `message`。\n\n- `\u003centity\u003e` — 标签只是「引用」，本身不含名称 / 图片 / 指标，只有 `type` / `id` / `region` / `platform`。要渲染成富卡片，凭 `id` 调对应的开放平台详情接口取数（商品 / 达人 / 店铺 / 视频各有独立接口）；`category`（品类）、货源类（`platform=\"1688\"` / `\"web\"`）信息已在属性里，无需取数。**详情接口按次计费**，一份报告常含多个 entity，建议懒加载 + 按 id 缓存，避免一次性查全造成不必要扣费。\n\n- `\u003cchart\u003e` — `type`：`bar`（对比）/ `line`（趋势）/ `pie`（占比），`title` 必填；body 为 JSON 数组，第一个字符串字段作 x 轴、第一个数值字段作 y 轴（同一对象多个数值字段时只取第一个，不堆叠）。\n\n**异步任务衔接** — 当 agent 触发视频 / 图片生成等耗时能力时，会发 `event: task`（含 `task_id`），且 `event: done` 的 `pending_tasks` 也会带上。用该 `task_id` 调 `GET /open/v1/tasks/{task_id}` 轮询最终结果。","operationId":"agentChat","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"attachments":[{"media_type":"image/jpeg","name":"product.jpg","os_bucket":"trenz-uploads","os_key":"u/123/2026-05/product_xxx.jpg"},{"media_type":"model","name":"model_reference.jpg","os_bucket":"trenz-uploads","os_key":"u/123/2026-05/model_yyy.jpg"}],"message":"用我刚上传的图片生成一段产品视频，模特穿着展示","model":"core","session_id":"454bb2c9-f972-4371-8525-d26cda19eedc"},"schema":{"properties":{"attachments":{"description":"可选。附加的对象存储资源引用（图片 / 模特图 / 视频）。每个引用必须含 `os_bucket` + `os_key`。","items":{"properties":{"media_type":{"description":"可选，默认 `image/jpeg`。可选值：`image/png`、`image/jpeg`、`video/mp4`、`model`（特殊：时装模特参考图，会被路由到产品视频生成工具的 `model_images` 入参而非 `images`）。","type":"string"},"name":{"description":"可选。文件名，给 LLM 的语义化标识。","type":"string"},"os_bucket":{"description":"必填。对象存储 bucket 名（如 `trenz-uploads`）。","type":"string"},"os_key":{"description":"必填。对象存储 object key（如 `u/123/2026-05/product_xxx.jpg`）。","type":"string"},"url":{"description":"可选。预签名 URL（用于 LLM 直接 fetch，如 `recognize_image`）。开放平台路径下需调方自己签好；仅靠 `os_bucket` + `os_key` 也能让下游工具索引使用。","type":"string"}},"required":["os_bucket","os_key"],"type":"object"},"type":"array"},"message":{"description":"用户消息内容。回应上一轮 `\u003cselect\u003e` widget 时，发送所选 option 的 `value` 属性作为消息文本。","type":"string"},"model":{"description":"可选。模型 codename：`core`（默认，能力更强，约 ¥1,250/1M）/ `aura`（更经济，约 ¥280/1M）。不传 = `core`。","enum":["core","aura"],"type":"string"},"session_id":{"description":"可选。继续已有会话。留空开启新会话；响应的 `event: init` 中会返回新分配的 `session_id`。","format":"uuid","type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"text/event-stream":{"example":"event: init\ndata: {\"session_id\": \"c3f1e8a2-7b14-4f9d-8c3a-1d4e5f6a7b8c\", \"agent_id\": \"trenzer\", \"estimated_seconds\": 5}\n\nevent: content\ndata: {\"text\": \"\\u597d\\u7684\\uff0c\\u6b63\\u5728\\u4e3a\\u4f60\\u751f\\u6210\\u4ea7\\u54c1\\u89c6\\u9891\\u3002\", \"seq\": 1}\n\nevent: tool\ndata: {\"name\": \"submit_product_video\", \"status\": \"calling\", \"display_name\": \"\\u4ea7\\u54c1\\u89c6\\u9891\\u751f\\u6210\", \"seq\": 2}\n\nevent: tool\ndata: {\"name\": \"submit_product_video\", \"status\": \"done\", \"duration_ms\": 412, \"summary\": \"\\u4efb\\u52a1\\u5df2\\u63d0\\u4ea4\", \"seq\": 3}\n\nevent: task\ndata: {\"task_id\": \"9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6\", \"tool_name\": \"submit_product_video\", \"display_name\": \"\\u4ea7\\u54c1\\u89c6\\u9891\\u751f\\u6210\", \"seq\": 4}\n\nevent: done\ndata: {\"stop_reason\": \"end_turn\", \"model\": \"core\", \"usage\": {\"input_tokens\": 142, \"output_tokens\": 38}, \"pending_tasks\": [{\"task_id\": \"9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6\", \"tool_name\": \"submit_product_video\"}], \"report_ids\": [], \"message_id\": \"a7b8c9d0-1234-5678-9abc-def012345678\", \"seq\": 5}\n","schema":{"description":"Server-Sent Events 事件流。HTTP 响应体是一系列事件，每事件格式：\n\n    event: \u003c事件类型\u003e\n    data: \u003cJSON 对象\u003e\n    (空行)\n\n`data` 为标准 JSON，非 ASCII 字符按 `\\uXXXX` 转义。**事件类型**：\n\n- `init` — 流开始（永远第一个）。\n    `data: { session_id: string, agent_id: string, estimated_seconds?: int }`\n\n- `agent` — 切换了专家 agent（如 `market-analyst`），仅状态提示。\n    `data: { agent_id: string, seq: int }`\n\n- `content` — 流式输出的 assistant 文本（零个或多个）。\n    `data: { text: string, seq: int }`\n\n  注意：text 可能含内联 XML 标签（`\u003creport\u003e`、`\u003centity\u003e`、`\u003cchart\u003e`、`\u003ctask-result\u003e`、`\u003cvideo-scripts\u003e`、`\u003cselect\u003e`、`\u003csuggestions\u003e`、`\u003cconnect\u003e`），且可能跨多个 `content` 事件分片——按 `seq` 累积完整文本后再解析（各标签语义见接口说明）。\n\n- `tool` — Tool 调用生命周期事件（零个或多个）。\n    `data: { name: string, status: \"calling\" | \"done\" | \"error\", display_name?: string, summary?: string, duration_ms?: int, seq: int }`\n\n- `task` — 异步任务已创建（耗时能力，如视频 / 图片生成）。用 `task_id` 调 `GET /open/v1/tasks/{task_id}` 轮询结果。\n    `data: { task_id: string, tool_name: string, display_name?: string, seq: int }`\n\n- `done` — 流结束（成功完成时永远是最后一个）。\n    `data: { stop_reason: string, model?: string, usage?: { input_tokens: int, output_tokens: int }, pending_tasks?: array, report_ids?: array, message_id?: string, seq?: int }`\n\n    注：`usage` 这里指 **LLM token 用量**（计费维度，依据 `output_tokens`），与 HTTP 信封的 `usage.credits_cost` / `usage.credits_balance` 不是一回事。`model` 回显本轮使用的 codename。`report_ids` 是本轮生成 / 更新的报告 id（已服务端持久化）；报告全文已在 `content` 流中，不代表要另取。\n\n    `stop_reason` 取值：\n    - `end_turn` — Turn 完成。\n    - `awaiting_user_input` — Turn 暂停，`content` 流中含 `\u003cselect\u003e` widget，需用户回复继续。\n    - `max_tokens` — LLM token 预算耗尽，响应被截断。\n    - `max_turns` — 达到单次请求最大 agent 轮次上限。\n    - `error` — 生成失败（详细错误通常前面以 `event: error` 出现）。\n    - `abort` — 客户端断开或上游中止。\n\n- `error` — 流中错误事件（可能出现在 `done` 之前或代替 `done`）。\n    `data: { message: string, code?: string }`\n    常见 `code`：`INSUFFICIENT_CREDITS`（余额为 0）。\n\n**保活** — 流中会周期性出现以 `:` 开头的 SSE 注释行（如 `: ping - \u003c时间戳\u003e`，约每 15 秒一次）。这是标准 SSE 注释（不属于任何 event），客户端必须忽略，不要当作事件或内容。\n\n**流终止** — `done` 或 `error` 后流结束（无恢复路径）。客户端应把连接关闭视为终态。\n\n**会话延续** — 把 `init` 返回的 `session_id` 在下一个请求里传入即可继续。不带 `session_id` 总是开新会话。","type":"string"}}},"description":"SSE 事件流（agent 响应）"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"AI Agent 对话（Server-Sent Events 流式响应）","tags":["小匠Agent/1.对话"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/ai/gpt-image-2/image/generation":{"post":{"description":"GPT-Image-2 AI 图片生成（基于 OpenAI GPT-Image-2 模型），支持参考图引导生成。\n\n\u003e 💡 **关于参考图片**\n\u003e\n\u003e 直接把公开可访问的图片 URL 通过 `images` 字段传入即可，本接口已在内部完整封装上游素材库流程，调用方无需单独调用素材库 API。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-gpt-image-2-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"function_type":{"default":"general_edit","description":"功能类型：general_edit=通用编辑, ai_clothing=AI 换装, product_image=商品图, digital_avatar=数字人参考, handheld_product=手持商品","enum":["general_edit","ai_clothing","product_image","digital_avatar","handheld_product"],"type":"string"},"image_size":{"default":"1K","description":"输出图片分辨率","enum":["1K","2K","4K"],"type":"string"},"images":{"description":"参考图片列表（推荐使用此字段，统一输入）","items":{"properties":{"url":{"description":"图片 URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"type":"array"},"prompt":{"description":"图片生成提示词，1-5000 字符","type":"string"},"ratio":{"default":"9:16","description":"输出图片宽高比","enum":["1:1","9:16","16:9"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":60}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务 ID，用于查询任务状态和结果","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"GPT-Image-2 图片生成","tags":["内容制作/2.AI 图片"],"x-billing-mode":"async_on_complete","x-coin-cost":60,"x-pricing":{"default_quantity":1,"default_tier":"1K","fallback_coin_cost":60,"mode":"per_unit","quantity_param":"","tier_param":"image_size","unit_price_map":{"1K":60,"2K":60,"4K":100}},"x-scope":"chuhaijiang.ai_image.write"}},"/open/v1/ai/nanobanana/image/generation":{"post":{"description":"Nanobanana AI 图片生成（基于 Google Gemini 多模态模型，SWRR 多 Provider 调度），支持参考图引导生成。\n\n\u003e 💡 **关于参考图片**\n\u003e\n\u003e 直接把公开可访问的图片 URL 通过 `images` 字段传入即可，本接口已在内部完整封装上游素材库流程，调用方无需单独调用素材库 API。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-nanobanana-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"function_type":{"default":"general_edit","description":"功能类型：general_edit=通用编辑, ai_clothing=AI 换装, product_image=商品图, digital_avatar=数字人参考, handheld_product=手持商品","enum":["general_edit","ai_clothing","product_image","digital_avatar","handheld_product"],"type":"string"},"image_size":{"default":"1K","description":"输出图片分辨率","enum":["1K","2K","4K"],"type":"string"},"images":{"description":"参考图片列表（推荐使用此字段，统一输入）","items":{"properties":{"url":{"description":"图片 URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"type":"array"},"prompt":{"description":"图片生成提示词，1-5000 字符","type":"string"},"ratio":{"default":"9:16","description":"输出图片宽高比","enum":["1:1","9:16","16:9"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":60}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务 ID，用于查询任务状态和结果","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Nanobanana 图片生成","tags":["内容制作/2.AI 图片"],"x-billing-mode":"async_on_complete","x-coin-cost":60,"x-pricing":{"default_quantity":1,"default_tier":"1K","fallback_coin_cost":60,"mode":"per_unit","quantity_param":"","tier_param":"image_size","unit_price_map":{"1K":60,"2K":60,"4K":100}},"x-scope":"chuhaijiang.ai_image.write"}},"/open/v1/ai/products/review-analysis":{"post":{"description":"产品用户评论智能分析\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-product-review-analysis","parameters":[{"description":"国家代码","in":"query","name":"country_code","schema":{"default":"us","type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_regenerate":{"default":false,"description":"是否强制重新分析","type":"boolean"},"product_id":{"description":"产品ID","type":"string"}},"required":["product_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":100}},"schema":{"properties":{"data":{"properties":{"product_id":{"description":"产品ID","type":"string"},"task_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"产品评论分析","tags":["内容制作/3.AI 文案"],"x-billing-mode":"async_on_complete","x-coin-cost":100,"x-scope":"chuhaijiang.ai.write"}},"/open/v1/ai/sd-pro-fast/video/generation":{"post":{"description":"SeeDance2.0 Pro Fast AI视频生成，支持多图、参考视频/音频、帧模式等高级功能，生成速度更快。\n\n\u003e 💡 **关于真人参考图片 / 参考视频**\n\u003e\n\u003e 上游「素材库 API」用于真人图片 / 视频的合规认证与提交。\n\u003e\n\u003e **🎯 本接口已在内部完整封装该流程，调用方无需单独调用素材库 API。**\n\u003e\n\u003e 直接把公开可访问的图片 / 视频 URL 通过 `images` 或 `reference_videos` 字段传入即可。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-sd-pro-fast-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"type":"string"},"audio":{"default":true,"type":"boolean"},"country_code":{"default":"us","type":"string"},"duration":{"default":5,"maximum":15,"minimum":4,"type":"integer"},"images":{"description":"多个参考图片列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"language":{"type":"string"},"prompt":{"description":"视频生成提示词，1-5000字符","type":"string"},"reference_audios":{"description":"参考音频列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"reference_videos":{"description":"参考视频列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"resolution":{"default":"720p","enum":["720p"],"type":"string"},"role_mode":{"default":"reference","enum":["reference","frame"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1575}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"SeeDance2.0 Pro Fast视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":1575,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":1575,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"720p":105}},"x-scope":"chuhaijiang.ai_video.write"}},"/open/v1/ai/sd-pro/video/generation":{"post":{"description":"SeeDance2.0 Pro AI视频生成，支持多图、参考视频/音频、帧模式等高级功能。\n\n\u003e 💡 **关于真人参考图片 / 参考视频**\n\u003e\n\u003e 上游「素材库 API」用于真人图片 / 视频的合规认证与提交。\n\u003e\n\u003e **🎯 本接口已在内部完整封装该流程，调用方无需单独调用素材库 API。**\n\u003e\n\u003e 直接把公开可访问的图片 / 视频 URL 通过 `images` 或 `reference_videos` 字段传入即可。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-sd-pro-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"type":"string"},"audio":{"default":true,"type":"boolean"},"country_code":{"default":"us","type":"string"},"duration":{"default":5,"maximum":15,"minimum":4,"type":"integer"},"images":{"description":"多个参考图片列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"language":{"type":"string"},"prompt":{"description":"视频生成提示词，1-5000字符","type":"string"},"reference_audios":{"description":"参考音频列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"reference_videos":{"description":"参考视频列表","items":{"properties":{"url":{"type":"string"}},"type":"object"},"type":"array"},"resolution":{"default":"720p","enum":["720p","1080p"],"type":"string"},"role_mode":{"default":"reference","enum":["reference","frame"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1950}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"SeeDance2.0 Pro视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":1950,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":1950,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":300,"720p":130}},"x-scope":"chuhaijiang.ai_video.write"}},"/open/v1/ai/videos/grok/generate":{"post":{"description":"Grok 1.5 视频生成，支持文生视频与图生视频。时长仅支持 6/10/15 秒：6/10 秒可不传参考图（文生视频）；15 秒必须提供参考图 image。输出分辨率 720p，支持 9:16 与 16:9 宽高比。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-grok-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","description":"宽高比","enum":["9:16","16:9"],"type":"string"},"duration":{"default":6,"description":"视频时长（秒），仅支持 6/10/15。6/10 秒可不传参考图（文生视频）；15 秒必须提供参考图 image","enum":[6,10,15],"type":"integer"},"image":{"description":"图片信息（图生视频参考图；6/10 秒可不传即文生视频，15 秒必须提供。点击展开查看详细字段）","properties":{"url":{"description":"图片URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"language":{"default":"default","description":"语言","type":"string"},"prompt":{"description":"视频生成提示词","type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1500}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Grok视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":1500,"x-pricing":{"default_quantity":6,"default_tier":"_default","fallback_coin_cost":1500,"mode":"per_unit","quantity_param":"duration","tier_param":"","unit_price_map":{"_default":100}},"x-scope":"chuhaijiang.ai.write"}},"/open/v1/ai/videos/happyhorse/generate":{"post":{"description":"Happy Horse AI 视频生成\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-happyhorse-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"9:16","description":"视频宽高比","enum":["9:16","16:9","1:1","4:3","3:4"],"type":"string"},"duration":{"default":5,"description":"视频时长秒数","maximum":15,"minimum":3,"type":"integer"},"images":{"description":"多个参考图片列表，最多5张","items":{"properties":{"url":{"description":"可访问的链接","type":"string"}},"type":"object"},"type":"array"},"language":{"default":"default","description":"语言","type":"string"},"prompt":{"description":"视频生成提示词","type":"string"},"resolution":{"default":"720p","description":"视频分辨率","enum":["720p","1080p"],"type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":3000}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Happy Horse 视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":3000,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":3000,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":300,"720p":120}},"x-scope":"chuhaijiang.ai.write"}},"/open/v1/ai/videos/scripts/breakdown-v2":{"post":{"description":"视频脚本结构化拆解分析（V2增强版）\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-video-scripts-breakdown-v2","parameters":[{"description":"语言","in":"query","name":"language","schema":{"default":"en","type":"string"}},{"description":"国家代码","in":"query","name":"country_code","schema":{"default":"us","type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_regenerate":{"default":false,"description":"是否强制重新生成","type":"boolean"},"video_id":{"description":"视频ID","type":"string"}},"required":["video_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":100}},"schema":{"properties":{"data":{"properties":{"task_id":{"description":"异步任务ID","type":"string"},"video_id":{"description":"视频ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频脚本拆解V2","tags":["内容制作/4.AI 分析"],"x-billing-mode":"async_on_complete","x-coin-cost":100,"x-scope":"chuhaijiang.ai.write"}},"/open/v1/ai/videos/veo3/generate":{"post":{"description":"Veo 3.1模型视频生成，支持多图输入\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-veo3-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aspect_ratio":{"default":"portrait","description":"视频比例","type":"string"},"duration":{"default":8,"description":"视频时长秒数","enum":[5,8],"type":"integer"},"image":{"description":"单张图片（可选，兼容旧格式，点击展开查看详细字段）","properties":{"url":{"description":"图片URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"images":{"description":"图片信息数组（可选，多图）","items":{"properties":{"url":{"description":"图片URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"type":"array"},"language":{"default":"default","description":"语言","type":"string"},"prompt":{"description":"视频生成提示词","type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":800}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Veo3视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":800,"x-pricing":{"default_quantity":8,"default_tier":"_default","fallback_coin_cost":800,"mode":"per_unit","quantity_param":"duration","tier_param":"","unit_price_map":{"_default":100}},"x-scope":"chuhaijiang.ai.write"}},"/open/v1/ai/videos/wan26/generate":{"post":{"description":"Wan2.6模型图生视频，支持720p/1080p\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。","operationId":"chuhaijiang-ai-wan26-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"duration":{"default":15,"description":"视频时长秒数","enum":[5,10,15],"type":"integer"},"image":{"description":"图片信息（必需，图生视频，点击展开查看详细字段）","properties":{"url":{"description":"图片URL（支持任意可访问的图片链接）","type":"string"}},"type":"object"},"language":{"default":"default","description":"语言","type":"string"},"prompt":{"description":"视频生成提示词","type":"string"},"resolution":{"default":"720p","description":"视频分辨率","enum":["720p","1080p"],"type":"string"}},"required":["image","prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1500}},"schema":{"properties":{"data":{"properties":{"job_id":{"description":"异步任务ID","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Wan2.6视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":1500,"x-pricing":{"default_quantity":15,"default_tier":"720p","fallback_coin_cost":1500,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":100,"720p":100}},"x-scope":"chuhaijiang.ai.write"}},"/open/v1/assets/collections":{"post":{"description":"分页浏览素材库（团队共享可见），支持关键词/语义搜索与类型筛选。响应中的 bucket_name + os_key 是素材的稳定对象存储坐标，可直接用于「画布原子操作」的 attach_asset 挂载到画布、或用于「画布素材签名」换取预览 URL。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-assets-collections-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"分页/筛选查询素材库藏品（collections）的请求；所有字段均可选","properties":{"content_type":{"description":"按内容类型筛选，如 image/video/text，可选","type":"string"},"created_after":{"description":"上传时间下界（Unix 秒，闭区间），可选","type":"integer"},"created_before":{"description":"上传时间上界（Unix 秒，闭区间），可选","type":"integer"},"exclude_types":{"description":"排除的类型列表，可选","items":{"description":"被排除的类型","type":"string"},"type":"array"},"keyword":{"description":"关键词搜索（触发关键词+语义混合检索），可选","type":"string"},"library_type":{"description":"素材库类型，缺省 collections，可选","type":"string"},"limit":{"description":"每页数量，可选","type":"integer"},"offset":{"description":"偏移量分页，可选","type":"integer"},"order":{"description":"排序方向 asc/desc，可选","type":"string"},"parent_id":{"description":"父文件夹 ID，列某个文件夹下的素材，可选","type":"string"},"perf_tier":{"description":"效果分层筛选 fire/good/mid/low（透传下游排序），可选","items":{"description":"效果层级","type":"string"},"type":"array"},"platform":{"description":"按平台筛选，可选","type":"string"},"product_id":{"description":"按关联商品 ID 筛选，可选","type":"string"},"publish_status":{"description":"按发布状态筛选，可选","type":"string"},"sort_by":{"description":"排序字段，如 created_at/views/engagement/gmv/orders，可选；效果类排序不可用时降级为时间序并置 sort_degraded","type":"string"},"source":{"description":"按来源多选 OR 过滤：creation/upload/tiktok_shop 等，可选","items":{"description":"来源标识","type":"string"},"type":"array"},"tag_filter":{"description":"标签筛选组列表，组内 OR、跨组 AND，可选","items":{"description":"标签筛选组；组内标签 OR、跨组 AND，与 content_type 等筛选叠加（点击展开查看详细字段）","properties":{"group_id":{"description":"标签组 ID，必填","type":"string"},"tag_ids":{"description":"该组内的标签 ID 列表（组内 OR），必填","items":{"description":"标签 ID","type":"string"},"type":"array"}},"required":["group_id","tag_ids"],"type":"object"},"type":"array"},"type":{"description":"节点类型筛选（如 folder），可选","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"素材库列表响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"items":{"description":"素材/文件夹列表；每项的 bucket_name + os_key 可直接用于画布 attach_asset 绑定素材","items":{"description":"素材/文件夹列表项（点击展开查看详细字段）","properties":{"ai_analyze_status":{"description":"AI 分析状态，可选","type":"string"},"bucket_name":{"description":"素材 OSS bucket；接画布 attach_asset 时作为 source.osBucket 使用","type":"string"},"children_count":{"description":"文件夹内子项数量，可选","type":"integer"},"children_type_counts":{"description":"文件夹内按 content_type 分组的子项数量，如 {\"image\":3,\"video\":2}；仅目录节点（点击展开查看详细字段）","type":"object"},"composition":{"description":"构图，仅图片，可选","type":"string"},"content":{"description":"文本类素材的正文内容，可选","type":"string"},"content_type":{"description":"内容类型，如 image/video/text 等","type":"string"},"cover_url":{"description":"封面预签名 URL，可选","type":"string"},"created_at":{"description":"创建时间（Unix 秒）","type":"integer"},"description":{"description":"素材内容描述（AI 生成），可选","type":"string"},"dominant_colors":{"description":"主色调，仅图片，可选","type":"string"},"download_url":{"description":"下载预签名 URL，可选","type":"string"},"duration":{"description":"视频/音频时长（秒），可选","type":"integer"},"ending_flag":{"description":"视频结尾标记，仅视频，可选","type":"string"},"failed_reason":{"description":"素材处理失败原因，可选","type":"string"},"has_embedding":{"description":"语义检索所需 embedding 是否存在，可选","type":"boolean"},"has_tag_suggestions":{"description":"AI 打标建议是否已算过，可选","type":"boolean"},"height":{"description":"图片/视频高度，可选","type":"integer"},"id":{"description":"素材/文件夹 ID","type":"string"},"keywords":{"description":"AI 关键词，仅服务搜索/打标匹配，不单独渲染","items":{"description":"关键词","type":"string"},"type":"array"},"library_type":{"description":"素材库类型，缺省 collections","type":"string"},"match_type":{"description":"混合搜索命中方式 keyword/semantic/both，仅 keyword 搜索时回传","type":"string"},"matched_segment":{"description":"语义命中来自视频某段时的时间戳 {start_time,end_time}（点击展开查看详细字段）","properties":{"end_time":{"description":"片段结束时间","type":"string"},"start_time":{"description":"片段起始时间","type":"string"}},"type":"object"},"meta":{"description":"扩展元信息，JSON 字符串，可选","type":"string"},"name":{"description":"素材/文件夹名称，可选","type":"string"},"ocr_position":{"description":"OCR 位置，仅图片，可选","type":"string"},"ocr_text":{"description":"OCR 文本，仅图片，可选","type":"string"},"ocr_translation":{"description":"OCR 译文，仅图片，可选","type":"string"},"os_key":{"description":"素材 OSS 对象 key；接画布 attach_asset 时作为 source.osKey 使用","type":"string"},"os_type":{"description":"对象存储类型，可选","type":"string"},"parent_id":{"description":"父文件夹 ID，可选","type":"string"},"preview_urls":{"description":"文件夹前若干素材的预签名封面，仅目录节点返回","items":{"description":"预签名封面 URL","type":"string"},"type":"array"},"product_id":{"description":"关联商品 ID，可选","type":"string"},"publish_status":{"description":"发布状态","type":"string"},"published_platforms":{"description":"已发布平台列表，可选","items":{"description":"平台标识","type":"string"},"type":"array"},"remark":{"description":"用户备注（区别于 description），可选","type":"string"},"scene":{"description":"画面场景，仅图片，可选","type":"string"},"size_kb":{"description":"文件大小（KB），可选","type":"integer"},"source":{"description":"素材来源，如 creation/upload/tiktok_shop 等","type":"string"},"source_id":{"description":"来源侧原始 ID，可选","type":"string"},"subject":{"description":"画面主体，仅图片，可选","type":"string"},"summary":{"description":"AI 摘要，可选","type":"string"},"thumbnail_url":{"description":"缩略图预签名 URL，可选","type":"string"},"type":{"description":"节点类型（如 folder 表示文件夹），可选","type":"string"},"updated_at":{"description":"更新时间（Unix 秒）","type":"integer"},"user_id":{"description":"归属用户 ID","type":"string"},"watermark_detected":{"description":"是否检测到水印，可选","type":"string"},"width":{"description":"图片/视频宽度，可选","type":"integer"}},"type":"object"},"type":"array"},"sort_degraded":{"description":"效果类排序是否降级为时间序（下游 ranking 不可用时为 true），可选","type":"boolean"},"status_counts":{"description":"按发布状态分组的计数（点击展开查看详细字段）","type":"object"},"total":{"description":"满足筛选的总条数，可选","type":"integer"},"type_counts":{"description":"按内容类型分组的计数，如 {\"image\":10,\"video\":5}（点击展开查看详细字段）","type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"素材库素材列表","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.assets.read"}},"/open/v1/assets/collections/detail":{"post":{"description":"查询单个素材的完整信息（含对象存储坐标、尺寸、AI 分析标签等），用于挂载到画布前确认素材内容。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-assets-collections-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"查询单个素材详情的请求","properties":{"id":{"description":"素材/文件夹 ID，必填","type":"string"}},"required":["id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"素材详情响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"item":{"description":"素材/文件夹详情（比列表项多 segments/subject_crops/tags 等）（点击展开查看详细字段）","properties":{"ai_analyze_status":{"description":"AI 分析状态，可选","type":"string"},"bucket_name":{"description":"素材 OSS bucket；接画布 attach_asset 时作为 source.osBucket 使用","type":"string"},"children_count":{"description":"文件夹内子项数量，可选","type":"integer"},"children_type_counts":{"description":"文件夹内按 content_type 分组的子项数量，如 {\"image\":3,\"video\":2}；仅目录节点（点击展开查看详细字段）","type":"object"},"composition":{"description":"构图，仅图片，可选","type":"string"},"content":{"description":"文本类素材的正文内容，可选","type":"string"},"content_type":{"description":"内容类型，如 image/video/text 等","type":"string"},"cover_url":{"description":"封面预签名 URL，可选","type":"string"},"created_at":{"description":"创建时间（Unix 秒）","type":"integer"},"description":{"description":"素材内容描述（AI 生成），可选","type":"string"},"dominant_colors":{"description":"主色调，仅图片，可选","type":"string"},"download_url":{"description":"下载预签名 URL，可选","type":"string"},"duration":{"description":"视频/音频时长（秒），可选","type":"integer"},"ending_flag":{"description":"视频结尾标记，仅视频，可选","type":"string"},"failed_reason":{"description":"素材处理失败原因，可选","type":"string"},"has_embedding":{"description":"语义检索所需 embedding 是否存在，可选","type":"boolean"},"has_tag_suggestions":{"description":"AI 打标建议是否已算过，可选","type":"boolean"},"height":{"description":"图片/视频高度，可选","type":"integer"},"id":{"description":"素材/文件夹 ID","type":"string"},"keywords":{"description":"AI 关键词，仅服务搜索/打标匹配，不单独渲染","items":{"description":"关键词","type":"string"},"type":"array"},"library_type":{"description":"素材库类型，缺省 collections","type":"string"},"match_type":{"description":"混合搜索命中方式 keyword/semantic/both，仅 keyword 搜索时回传","type":"string"},"matched_segment":{"description":"语义命中来自视频某段时的时间戳 {start_time,end_time}（点击展开查看详细字段）","properties":{"end_time":{"description":"片段结束时间","type":"string"},"start_time":{"description":"片段起始时间","type":"string"}},"type":"object"},"meta":{"description":"扩展元信息，JSON 字符串，可选","type":"string"},"name":{"description":"素材/文件夹名称，可选","type":"string"},"ocr_position":{"description":"OCR 位置，仅图片，可选","type":"string"},"ocr_text":{"description":"OCR 文本，仅图片，可选","type":"string"},"ocr_translation":{"description":"OCR 译文，仅图片，可选","type":"string"},"os_key":{"description":"素材 OSS 对象 key；接画布 attach_asset 时作为 source.osKey 使用","type":"string"},"os_type":{"description":"对象存储类型，可选","type":"string"},"parent_folder_name":{"description":"tag_filter 跨文件夹平铺时所在文件夹名，可选","type":"string"},"parent_id":{"description":"父文件夹 ID，可选","type":"string"},"preview_urls":{"description":"文件夹前若干素材的预签名封面，仅目录节点返回","items":{"description":"预签名封面 URL","type":"string"},"type":"array"},"product_id":{"description":"关联商品 ID，可选","type":"string"},"publish_status":{"description":"发布状态","type":"string"},"published_platforms":{"description":"已发布平台列表，可选","items":{"description":"平台标识","type":"string"},"type":"array"},"remark":{"description":"用户备注（区别于 description），可选","type":"string"},"scene":{"description":"画面场景，仅图片，可选","type":"string"},"segments":{"description":"视频分段分析结果，仅视频且仅 detail 接口返回","items":{"description":"视频片段分析（点击展开查看详细字段）","properties":{"action":{"description":"动作","type":"string"},"camera_movement":{"description":"运镜","type":"string"},"end_time":{"description":"片段结束时间","type":"string"},"face_count":{"description":"人脸数","type":"string"},"logo_detected":{"description":"是否检测到 logo","type":"string"},"ocr_position":{"description":"OCR 位置","type":"string"},"ocr_text":{"description":"片段内 OCR 文本","type":"string"},"ocr_translation":{"description":"OCR 译文","type":"string"},"product_visible":{"description":"商品是否可见","type":"string"},"scene":{"description":"场景","type":"string"},"script_structure":{"description":"脚本结构标注","type":"string"},"shot_type":{"description":"景别","type":"string"},"start_time":{"description":"片段起始时间","type":"string"},"subject":{"description":"主体","type":"string"},"transcript":{"description":"语音转写文本","type":"string"},"transcript_translation":{"description":"转写译文","type":"string"}},"type":"object"},"type":"array"},"size_kb":{"description":"文件大小（KB），可选","type":"integer"},"sort_order":{"description":"文件夹树排序值；DB BIGINT 以十进制字符串返回，前端不得参与计算","type":"string"},"source":{"description":"素材来源，如 creation/upload/tiktok_shop 等","type":"string"},"source_id":{"description":"来源侧原始 ID，可选","type":"string"},"subject":{"description":"画面主体，仅图片，可选","type":"string"},"subject_crops":{"description":"主体裁剪图（人脸/商品），仅 detail 接口返回","items":{"description":"主体裁剪图（点击展开查看详细字段）","properties":{"bucket_name":{"description":"裁剪图 OSS bucket","type":"string"},"label":{"description":"标签，可选","type":"string"},"os_key":{"description":"裁剪图 OSS key","type":"string"},"os_type":{"description":"对象存储类型，可选","type":"string"},"preview_url":{"description":"预签名可展示 URL，服务端生成","type":"string"},"subject_type":{"description":"主体类型：face / product","type":"string"}},"type":"object"},"type":"array"},"summary":{"description":"AI 摘要，可选","type":"string"},"tags":{"description":"素材当前正式标签，仅 detail 接口返回","items":{"description":"标签（点击展开查看详细字段）","properties":{"created_at":{"description":"创建时间（Unix 秒）","type":"integer"},"description":{"description":"标签描述，可选","type":"string"},"display_order":{"description":"显示顺序，可选","type":"integer"},"id":{"description":"标签 ID","type":"string"},"name":{"description":"标签名","type":"string"},"tag_group_id":{"description":"所属标签组 ID，可选","type":"string"},"tag_group_name":{"description":"标签组名称，可选","type":"string"},"updated_at":{"description":"更新时间（Unix 秒）","type":"integer"}},"type":"object"},"type":"array"},"thumbnail_url":{"description":"缩略图预签名 URL，可选","type":"string"},"type":{"description":"节点类型（如 folder 表示文件夹），可选","type":"string"},"updated_at":{"description":"更新时间（Unix 秒）","type":"integer"},"user_id":{"description":"归属用户 ID","type":"string"},"watermark_detected":{"description":"是否检测到水印，可选","type":"string"},"width":{"description":"图片/视频宽度，可选","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"素材库素材详情","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.assets.read"}},"/open/v1/auth/verify":{"get":{"description":"用 API Key 查询当前账户的基础信息：所属 user / app、tier 定价等级、credits 余额、账户状态。免费接口，不扣 credits。","operationId":"auth-verify","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"app_id":1024,"credits_balance":12450,"status":"active","tier":"payg","user_id":"u_abc123"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"app_id":{"description":"Application ID","format":"int64","type":"integer"},"credits_balance":{"description":"剩余 credits 余额","format":"int64","type":"integer"},"status":{"description":"账户状态：`active` / `suspended` / `revoked` / `deleted`","type":"string"},"tier":{"description":"定价等级（由控制面定义，如 `payg` / `tenant_basic`）","type":"string"},"user_id":{"description":"User ID","type":"string"}},"required":["user_id","app_id","tier","credits_balance","status"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询账户状态与 credits 余额","tags":["账户"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/canvas/apply":{"post":{"description":"画布核心写入接口：以原子批量方式执行操作列表（重命名/加删改节点/加删边/挂载素材/绑定生成任务/设置视口，共 10 种），全部成功或全部回滚。必须携带 expected_revision 乐观锁（从「读取画布」或上次变更响应获取）；版本不匹配返回 409 并附 current_revision，拉取最新后重试。单次最多 200 个操作。挂载素材（attach_asset）要求素材归属证明：本人上传登记、本人素材库、或本人生成任务产物三选一。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-apply","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"以乐观锁方式对画布批量应用增量操作的请求","properties":{"canvas_id":{"description":"目标画布 ID，必填","type":"string"},"expected_revision":{"description":"当前画布版本号，从 load 或上次变更响应获取；不匹配时返回 409 并在响应 current_revision 附最新版本号。必须为正数","type":"integer"},"operations":{"description":"有序操作列表，单次最多 200 条，按序应用；任一条失败则整批回滚","items":{"description":"单条画布操作；type 决定语义，其余字段按 type 取用（点击展开查看详细字段）","properties":{"asset":{"description":"attach_asset 用：稳定素材引用，含 mediaType 与 source（source.kind=oss 时带 osBucket+osKey）（点击展开查看详细字段）","type":"object"},"edge":{"description":"add_edge 用：完整新连线对象，须含 id/source/target（点击展开查看详细字段）","type":"object"},"edge_id":{"description":"remove_edge 用：目标连线 ID","type":"string"},"name":{"description":"rename_canvas 用：新的画布名称","type":"string"},"node":{"description":"add_node 用：完整新节点对象，须含 id 与 type（image/video/text），不得含 url/src 等运行时字段（点击展开查看详细字段）","type":"object"},"node_id":{"description":"update_node/remove_node/attach_asset/detach_asset/bind_generation_task 用：目标节点 ID","type":"string"},"patch":{"description":"update_node 用：节点局部更新补丁，深合并进节点；不得改 type 或 asset/generation 等受保护字段（点击展开查看详细字段）","type":"object"},"task":{"description":"bind_generation_task 用：生成任务引用，含 taskId、toolName、status 及可选 inputs/config 等（点击展开查看详细字段）","type":"object"},"type":{"description":"操作类型（枚举）：\n- rename_canvas：重命名画布，用 name 字段\n- add_node：新增节点，用 node 字段（node.id 必填、type 限 image/video/text，不能带运行时 URL 字段）\n- update_node：局部更新节点，用 node_id + patch（不能改 type、asset、generation 等受保护字段）\n- remove_node：删除节点，用 node_id（同时清理关联的边）\n- add_edge：新增连线，用 edge 字段（edge.id/source/target 必填且节点须存在）\n- remove_edge：删除连线，用 edge_id\n- attach_asset：给节点绑定稳定素材，用 node_id + asset（asset.source.kind=oss 时需 osBucket+osKey，媒体类型须与节点一致，会校验素材归属）\n- detach_asset：解绑节点素材，用 node_id\n- bind_generation_task：把生成任务绑到节点，用 node_id + task（task.taskId 必填，toolName 须与节点类型匹配）\n- set_viewport：设置视口，用 value 字段（含 x/y/zoom）","enum":["rename_canvas","add_node","update_node","remove_node","add_edge","remove_edge","attach_asset","detach_asset","bind_generation_task","set_viewport"],"type":"string"},"value":{"description":"set_viewport 用：视口对象 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","type":"object"}},"required":["type"],"type":"object"},"type":"array"},"source_client_id":{"description":"调用方客户端标识，可选；用于服务端在推送画布变更 WebSocket 事件时回声去重（把变更来源标回给发起端），不影响业务结果","type":"string"}},"required":["canvas_id","expected_revision","operations"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"画布变更通用响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"current_revision":{"description":"乐观锁冲突时返回的服务端当前版本号，成功时缺省","type":"integer"},"deleted":{"description":"是否为删除响应；apply 场景恒为 false 或缺省","type":"boolean"},"document":{"description":"应用操作后的最新画布文档，revision 已自增（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识，如 chj","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"payload":{"description":"画布完整文档，持久化后的稳定结构，不含任何运行时预览 URL（运行时 URL 需另调 hydrate 接口换取）；契约详见画布文档（点击展开查看详细字段）","properties":{"edges":{"description":"画布连线列表；每条边含 id/source/target，source 与 target 必须指向已存在的节点 id","items":{"description":"画布连线（点击展开查看详细字段）","properties":{"id":{"description":"连线唯一 ID","type":"string"},"source":{"description":"起点节点 ID","type":"string"},"target":{"description":"终点节点 ID","type":"string"}},"type":"object"},"type":"array"},"name":{"description":"画布名称，与外层 name 一致","type":"string"},"nodes":{"description":"画布节点列表；每个节点含 id/type/position/data，type 限 image/video/text（audio/script 为兼容保留）","items":{"description":"画布节点（点击展开查看详细字段）","properties":{"data":{"description":"节点业务数据，含 type、绑定素材 asset、生成任务 generation/textGeneration/audioGeneration 等稳定字段（点击展开查看详细字段）","type":"object"},"id":{"description":"节点唯一 ID","type":"string"},"position":{"description":"节点在画布中的坐标 {x, y}（点击展开查看详细字段）","properties":{"x":{"description":"横坐标","type":"number"},"y":{"description":"纵坐标","type":"number"}},"type":"object"},"type":{"description":"节点类型：image/video/text（audio/script 兼容保留）","type":"string"}},"type":"object"},"type":"array"},"ownerKey":{"description":"画布归属键，格式 canvas:{brand}:{userId}:{canvasId}:v1，服务端生成","type":"string"},"savedAt":{"description":"画布最近一次保存时间（RFC3339Nano）","type":"string"},"version":{"description":"画布文档结构版本号，当前为 1","type":"integer"},"viewport":{"description":"画布视口 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，正数","type":"number"}},"type":"object"}},"type":"object"},"revision":{"description":"画布版本号，每次成功变更自增，用作乐观锁；下次 apply/delete 需回传该值","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，通常由网关按 API Key 注入；响应中可能省略","type":"string"}},"type":"object"},"error_code":{"description":"业务错误码（如 revision_conflict/asset_not_accessible/invalid_operation），成功时缺省","type":"string"},"revision":{"description":"删除操作回传的最新版本号，apply 场景缺省","type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"画布原子操作","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/assets/hydrate":{"post":{"description":"将素材的对象存储坐标（os_bucket + os_key）批量换取 24 小时有效的签名访问 URL，用于预览画布中的图片/视频素材。坐标来自画布节点的 data.asset.source、素材库列表、或生成任务结果。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-assets-hydrate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"把画布节点的稳定 OSS 引用换成运行时可访问签名 URL 的请求（返回的 URL 不要持久化，仅运行时使用）","properties":{"refs":{"description":"待换取运行时 URL 的稳定素材引用列表；每项传 os_bucket + os_key（可选 media_type），服务端去重后逐一预签名。空 bucket/key 的项被跳过","items":{"description":"稳定素材引用（点击展开查看详细字段）","properties":{"media_type":{"description":"媒体类型 image/video/audio，可选；原样回传","type":"string"},"os_bucket":{"description":"素材所在 OSS bucket，必填","type":"string"},"os_key":{"description":"素材 OSS 对象 key，必填","type":"string"}},"required":["os_bucket","os_key"],"type":"object"},"type":"array"}},"required":["refs"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"素材 hydrate 响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"items":{"description":"换取到的素材 URL 列表，与请求 refs 去重后一一对应；签名失败或空 URL 的项被剔除","items":{"description":"带签名 URL 的素材项（点击展开查看详细字段）","properties":{"media_type":{"description":"媒体类型，回显请求值，可能缺省","type":"string"},"os_bucket":{"description":"素材 OSS bucket","type":"string"},"os_key":{"description":"素材 OSS 对象 key","type":"string"},"url":{"description":"预签名运行时访问 URL，有效期 24 小时；仅运行时使用，不得持久化到画布","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"画布素材签名","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/canvas/create":{"post":{"description":"创建一个空画布文档，服务端生成画布 ID，初始版本号 revision=1。画布是 AI 图片/视频创作工作台：素材卡片（图片/视频/文本/音频节点）+ 无向连线表达生成上下文。创建后用「画布原子操作」接口添加节点和连线。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-create","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"创建一张空白画布的请求","properties":{"name":{"description":"画布名称，可选；缺省为「新画布」，最长 255 字节","type":"string"},"source_client_id":{"description":"调用方客户端标识，可选；用于服务端在推送画布变更 WebSocket 事件时回声去重（把变更来源标回给发起端），不影响业务结果","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"画布变更通用响应（create/apply/delete 共用）","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"current_revision":{"description":"发生乐观锁冲突时返回的服务端当前版本号，成功时缺省","type":"integer"},"deleted":{"description":"是否为删除操作产生的响应；创建场景恒为 false 或缺省","type":"boolean"},"document":{"description":"新建的画布文档，含初始空 nodes/edges，revision 为 1（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识，如 chj","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"payload":{"description":"画布完整文档，持久化后的稳定结构，不含任何运行时预览 URL（运行时 URL 需另调 hydrate 接口换取）；契约详见画布文档（点击展开查看详细字段）","properties":{"edges":{"description":"画布连线列表；每条边含 id/source/target，source 与 target 必须指向已存在的节点 id","items":{"description":"画布连线（点击展开查看详细字段）","properties":{"id":{"description":"连线唯一 ID","type":"string"},"source":{"description":"起点节点 ID","type":"string"},"target":{"description":"终点节点 ID","type":"string"}},"type":"object"},"type":"array"},"name":{"description":"画布名称，与外层 name 一致","type":"string"},"nodes":{"description":"画布节点列表；每个节点含 id/type/position/data，type 限 image/video/text（audio/script 为兼容保留）","items":{"description":"画布节点（点击展开查看详细字段）","properties":{"data":{"description":"节点业务数据，含 type、绑定素材 asset、生成任务 generation/textGeneration/audioGeneration 等稳定字段（点击展开查看详细字段）","type":"object"},"id":{"description":"节点唯一 ID","type":"string"},"position":{"description":"节点在画布中的坐标 {x, y}（点击展开查看详细字段）","properties":{"x":{"description":"横坐标","type":"number"},"y":{"description":"纵坐标","type":"number"}},"type":"object"},"type":{"description":"节点类型：image/video/text（audio/script 兼容保留）","type":"string"}},"type":"object"},"type":"array"},"ownerKey":{"description":"画布归属键，格式 canvas:{brand}:{userId}:{canvasId}:v1，服务端生成","type":"string"},"savedAt":{"description":"画布最近一次保存时间（RFC3339Nano）","type":"string"},"version":{"description":"画布文档结构版本号，当前为 1","type":"integer"},"viewport":{"description":"画布视口 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，正数","type":"number"}},"type":"object"}},"type":"object"},"revision":{"description":"画布版本号，每次成功变更自增，用作乐观锁；下次 apply/delete 需回传该值","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，通常由网关按 API Key 注入；响应中可能省略","type":"string"}},"type":"object"},"error_code":{"description":"业务错误码（如 revision_conflict/permission_denied），成功时缺省","type":"string"},"revision":{"description":"删除操作回传的最新版本号，创建场景缺省","type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"创建画布","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/delete":{"post":{"description":"软删除画布（可携带 expected_revision 乐观锁防误删）。删除后画布不再出现在列表中。画布无版本历史，删除前建议先用「创建画布分享」创建快照作为冻结备份。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-delete","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"软删除一张画布的请求","properties":{"canvas_id":{"description":"目标画布 ID，必填","type":"string"},"expected_revision":{"description":"当前画布版本号，从 load 或上次变更响应获取；不匹配时返回 409 并附 current_revision。必须为正数","type":"integer"},"source_client_id":{"description":"调用方客户端标识，可选；用于服务端在推送画布变更 WebSocket 事件时回声去重（把变更来源标回给发起端），不影响业务结果","type":"string"}},"required":["canvas_id","expected_revision"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"画布删除响应（画布变更通用响应结构）","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"current_revision":{"description":"乐观锁冲突时返回的服务端当前版本号，成功时缺省","type":"integer"},"deleted":{"description":"删除成功恒为 true","type":"boolean"},"document":{"description":"删除场景通常缺省；仅保留字段占位（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识，如 chj","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"payload":{"description":"画布完整文档，持久化后的稳定结构，不含任何运行时预览 URL（运行时 URL 需另调 hydrate 接口换取）；契约详见画布文档（点击展开查看详细字段）","properties":{"edges":{"description":"画布连线列表；每条边含 id/source/target，source 与 target 必须指向已存在的节点 id","items":{"description":"画布连线（点击展开查看详细字段）","properties":{"id":{"description":"连线唯一 ID","type":"string"},"source":{"description":"起点节点 ID","type":"string"},"target":{"description":"终点节点 ID","type":"string"}},"type":"object"},"type":"array"},"name":{"description":"画布名称，与外层 name 一致","type":"string"},"nodes":{"description":"画布节点列表；每个节点含 id/type/position/data，type 限 image/video/text（audio/script 为兼容保留）","items":{"description":"画布节点（点击展开查看详细字段）","properties":{"data":{"description":"节点业务数据，含 type、绑定素材 asset、生成任务 generation/textGeneration/audioGeneration 等稳定字段（点击展开查看详细字段）","type":"object"},"id":{"description":"节点唯一 ID","type":"string"},"position":{"description":"节点在画布中的坐标 {x, y}（点击展开查看详细字段）","properties":{"x":{"description":"横坐标","type":"number"},"y":{"description":"纵坐标","type":"number"}},"type":"object"},"type":{"description":"节点类型：image/video/text（audio/script 兼容保留）","type":"string"}},"type":"object"},"type":"array"},"ownerKey":{"description":"画布归属键，格式 canvas:{brand}:{userId}:{canvasId}:v1，服务端生成","type":"string"},"savedAt":{"description":"画布最近一次保存时间（RFC3339Nano）","type":"string"},"version":{"description":"画布文档结构版本号，当前为 1","type":"integer"},"viewport":{"description":"画布视口 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，正数","type":"number"}},"type":"object"}},"type":"object"},"revision":{"description":"画布版本号，每次成功变更自增，用作乐观锁；下次 apply/delete 需回传该值","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，通常由网关按 API Key 注入；响应中可能省略","type":"string"}},"type":"object"},"error_code":{"description":"业务错误码（如 revision_conflict/not_found），成功时缺省","type":"string"},"revision":{"description":"删除后的最新版本号（软删除也会自增 revision）","type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"删除画布","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/generate":{"post":{"description":"对画布节点发起服务端组装生成（一步闭环）：平台读取节点生成草稿与一跳连线上下文，按权威规则组装参数（文本展开、参考图角色分配、@引用解析、Seedance 系字段路由），提交生成任务并自动绑定到执行节点（自动携带完整 config）。支持 image/video/text/audio 四种节点。费用同「画布生成任务提交」：按出海贝扣除。画布内生成推荐一律使用本接口；「画布生成任务提交」+ bind 两步式仅用于需要完全自定义参数的场景。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"对画布上的一个节点发起服务端组装生成：平台从节点的生成草稿与一跳连线上下文按权威规则组装参数（文本展开进 prompt、参考图角色分配、@引用解析、Seedance 系字段路由等），提交生成任务并自动绑定到执行节点。相比「画布生成任务提交」+ bind 两步式，本接口一步闭环且无需理解组装规则，画布内生成推荐一律使用本接口。","properties":{"canvas_id":{"description":"画布 ID","type":"string"},"expected_revision":{"description":"当前画布版本号（乐观锁），从「读取画布」或上次变更响应获取；不匹配时返回 409 并附 current_revision","type":"integer"},"generation":{"description":"生成参数覆盖对象，可选（点击展开查看详细字段）。与节点已存的生成草稿（generationDraft）按键合并，本对象优先；键名用 camelCase。字段说明中的〔图片〕〔视频〕〔TTS〕标注了适用的节点类型。提示词请用顶层 prompt 字段传，不要放在本对象里","properties":{"aspectRatio":{"description":"〔视频〕画幅比例（如 16:9 / 9:16 / 1:1，可选值随模型能力而定）","type":"string"},"duration":{"description":"〔视频〕时长（秒），档位随模型而定（如 sd 系 5/10/15）。视频费用 = 模型×分辨率每秒单价 × duration","type":"integer"},"imageSize":{"description":"〔图片〕清晰度：1K / 2K / 4K，图片生成的计费依据","type":"string"},"inputMode":{"description":"〔视频〕参考素材使用方式：none / reference（全能参考）/ first-frame（首帧）/ first-last-frame（首尾帧）。不传时服务端按模型与上下文素材自动推导","type":"string"},"instruction":{"description":"〔TTS·自定义音色〕演绎指令，可选","type":"string"},"instructions":{"description":"〔TTS·系统音色〕演绎指令，可选","type":"string"},"kind":{"description":"生成种类：image / video / text / audio。缺省自动取目标节点类型，显式传入时必须与节点类型一致","type":"string"},"language":{"description":"〔视频〕口播/文案语种；〔TTS〕合成语种（均可选）","type":"string"},"model":{"description":"〔图片/视频〕生成模型。图片：nanobanana / gpt_image_2；视频：sd_pro / sd_pro_fast / sd_pro_mini（Seedance 系）/ happyhorse / grok / veo31 / wan26 / sora2 / sora_pro","type":"string"},"pitch":{"description":"〔TTS·自定义音色〕音调调整，可选","type":"number"},"rate":{"description":"〔TTS·自定义音色〕语速调整，可选","type":"number"},"ratio":{"description":"〔图片〕画幅比例：1:1（方图）/ 9:16（竖图）/ 16:9（横图）","enum":["1:1","9:16","16:9"],"type":"string"},"resolution":{"description":"〔视频〕分辨率：480p / 720p / 1080p（可选值随模型而定），影响每秒单价","type":"string"},"responseFormat":{"description":"〔TTS·系统音色〕输出格式，默认 mp3","type":"string"},"sourceType":{"description":"〔TTS〕音色来源：system_voice（系统音色）/ voice_profile（自定义音色，来自出海匠「声音资产」）。本接口的 TTS 走新通道，支持自定义音色","type":"string"},"speed":{"description":"〔TTS·系统音色〕语速，默认 1","type":"number"},"text":{"description":"〔TTS〕合成台词（也可直接用顶层 prompt 字段传）","type":"string"},"voice":{"description":"〔TTS·系统音色〕音色名（system_voice 时必填）","type":"string"},"voiceProfileId":{"description":"〔TTS·自定义音色〕音色档案 ID（voice_profile 时必填）","type":"string"},"volume":{"description":"〔TTS·自定义音色〕音量调整，可选","type":"number"}},"type":"object"},"input_node_ids":{"description":"限定参与组装的上下文节点 ID 列表，可选；不传则自动收集目标节点的一跳连线邻居","items":{"type":"string"},"type":"array"},"prompt":{"description":"生成提示词，可选。三级取值：本字段 \u003e 节点已存草稿的 prompt（含 @图片1 等引用的服务端解析）\u003e 由一跳上下文自动推导。audio 节点时本字段作为合成台词文本","type":"string"},"source_client_id":{"description":"调用方客户端标识，可选；用于画布变更通知的来源区分","type":"string"},"target_node_id":{"description":"目标节点 ID，支持 image / video / text / audio 四种节点类型；生成种类由节点类型决定","type":"string"}},"required":["canvas_id","target_node_id","expected_revision"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"基础响应：code=0 表示成功，msg 为错误信息（点击展开查看详细字段）","type":"object"},"current_revision":{"description":"发生 409 版本冲突时返回的当前画布版本号","type":"integer"},"document":{"description":"生成提交并绑定后的画布文档完整记录（含 payload 与新 revision），后续写操作以其中 revision 为乐观锁依据（点击展开查看详细字段）","type":"object"},"error_code":{"description":"业务错误码（如 REVISION_CONFLICT / NODE_NOT_FOUND / ASSET_NOT_ACCESSIBLE），成功时为空","type":"string"},"execution_node_id":{"description":"实际承载本次生成的节点 ID：目标节点为空时复用目标节点，已有内容时自动分支出新版本节点","type":"string"},"session_id":{"description":"任务所属会话 ID","type":"string"},"task_id":{"description":"生成任务 UUID，用「生成任务详情 / 批量详情」轮询至终态；任务完成后产物由平台回填画布","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"画布节点生成","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/list":{"post":{"description":"游标分页列出当前用户的画布，返回轻量摘要（名称、节点数、媒体节点数、边数、封面、更新时间），不含完整 payload。用 next_cursor 翻页，has_more=false 表示到底。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"分页列出当前用户画布的请求","properties":{"cursor":{"description":"分页游标，可选；传上一页响应的 next_cursor 拉下一页，首页不传","type":"string"},"limit":{"description":"每页返回数量，可选；缺省 100，最大 200","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"画布列表响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"documents":{"description":"画布摘要列表，按 updated_at 倒序","items":{"description":"画布列表项（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"cover":{"description":"封面素材的稳定引用，取自首个带 OSS 素材的图片/视频节点；无则缺省（点击展开查看详细字段）","properties":{"media_type":{"description":"封面素材类型 image/video","type":"string"},"os_bucket":{"description":"封面素材 OSS bucket","type":"string"},"os_key":{"description":"封面素材 OSS key","type":"string"}},"type":"object"},"cover_url":{"description":"封面预签名 URL，服务端按 cover 现签，24 小时有效；无封面时缺省","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"edge_count":{"description":"画布连线总数","type":"integer"},"media_node_count":{"description":"已绑定素材的图片/视频节点数","type":"integer"},"name":{"description":"画布名称","type":"string"},"node_count":{"description":"画布节点总数","type":"integer"},"revision":{"description":"画布版本号","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，可能省略","type":"string"}},"type":"object"},"type":"array"},"has_more":{"description":"是否还有下一页","type":"boolean"},"next_cursor":{"description":"下一页游标；无更多数据时缺省","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"画布列表","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/canvas/load":{"post":{"description":"读取画布完整内容（payload：节点/边/视口）与当前版本号 revision。仅画布所有者可读，不存在或非本人返回 404。写操作前先 load 获取 revision 作为乐观锁依据。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-load","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"加载单张画布文档的请求","properties":{"canvas_id":{"description":"画布 ID，可选；缺省用 \"default\" 加载默认画布","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"画布加载响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"document":{"description":"画布文档；画布不存在时该字段缺省（此时 base_resp.code 仍为 0）（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识，如 chj","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"payload":{"description":"画布完整文档，持久化后的稳定结构，不含任何运行时预览 URL（运行时 URL 需另调 hydrate 接口换取）；契约详见画布文档（点击展开查看详细字段）","properties":{"edges":{"description":"画布连线列表；每条边含 id/source/target，source 与 target 必须指向已存在的节点 id","items":{"description":"画布连线（点击展开查看详细字段）","properties":{"id":{"description":"连线唯一 ID","type":"string"},"source":{"description":"起点节点 ID","type":"string"},"target":{"description":"终点节点 ID","type":"string"}},"type":"object"},"type":"array"},"name":{"description":"画布名称，与外层 name 一致","type":"string"},"nodes":{"description":"画布节点列表；每个节点含 id/type/position/data，type 限 image/video/text（audio/script 为兼容保留）","items":{"description":"画布节点（点击展开查看详细字段）","properties":{"data":{"description":"节点业务数据，含 type、绑定素材 asset、生成任务 generation/textGeneration/audioGeneration 等稳定字段（点击展开查看详细字段）","type":"object"},"id":{"description":"节点唯一 ID","type":"string"},"position":{"description":"节点在画布中的坐标 {x, y}（点击展开查看详细字段）","properties":{"x":{"description":"横坐标","type":"number"},"y":{"description":"纵坐标","type":"number"}},"type":"object"},"type":{"description":"节点类型：image/video/text（audio/script 兼容保留）","type":"string"}},"type":"object"},"type":"array"},"ownerKey":{"description":"画布归属键，格式 canvas:{brand}:{userId}:{canvasId}:v1，服务端生成","type":"string"},"savedAt":{"description":"画布最近一次保存时间（RFC3339Nano）","type":"string"},"version":{"description":"画布文档结构版本号，当前为 1","type":"integer"},"viewport":{"description":"画布视口 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，正数","type":"number"}},"type":"object"}},"type":"object"},"revision":{"description":"画布版本号，每次成功变更自增，用作乐观锁；下次 apply/delete 需回传该值","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，通常由网关按 API Key 注入；响应中可能省略","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"读取画布","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/canvas/share/clone":{"post":{"description":"把一个分享快照克隆为自己名下的新画布（数据恢复通道：误删/误改后从冻结快照找回，或复制他人分享的画布结构）。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-share-clone","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"把一个分享画布克隆到当前用户名下的请求（需具备创建画布的版本权限）","properties":{"name":{"description":"克隆后的新画布名称，可选；缺省为「原名 + 副本」","type":"string"},"token":{"description":"分享令牌，必填；将该分享快照克隆为调用者名下的新画布","type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"分享克隆响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"document":{"description":"克隆生成的新画布文档，归属当前用户，含新的 canvas_id（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识，如 chj","type":"string"},"canvas_id":{"description":"画布唯一 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"payload":{"description":"画布完整文档，持久化后的稳定结构，不含任何运行时预览 URL（运行时 URL 需另调 hydrate 接口换取）；契约详见画布文档（点击展开查看详细字段）","properties":{"edges":{"description":"画布连线列表；每条边含 id/source/target，source 与 target 必须指向已存在的节点 id","items":{"description":"画布连线（点击展开查看详细字段）","properties":{"id":{"description":"连线唯一 ID","type":"string"},"source":{"description":"起点节点 ID","type":"string"},"target":{"description":"终点节点 ID","type":"string"}},"type":"object"},"type":"array"},"name":{"description":"画布名称，与外层 name 一致","type":"string"},"nodes":{"description":"画布节点列表；每个节点含 id/type/position/data，type 限 image/video/text（audio/script 为兼容保留）","items":{"description":"画布节点（点击展开查看详细字段）","properties":{"data":{"description":"节点业务数据，含 type、绑定素材 asset、生成任务 generation/textGeneration/audioGeneration 等稳定字段（点击展开查看详细字段）","type":"object"},"id":{"description":"节点唯一 ID","type":"string"},"position":{"description":"节点在画布中的坐标 {x, y}（点击展开查看详细字段）","properties":{"x":{"description":"横坐标","type":"number"},"y":{"description":"纵坐标","type":"number"}},"type":"object"},"type":{"description":"节点类型：image/video/text（audio/script 兼容保留）","type":"string"}},"type":"object"},"type":"array"},"ownerKey":{"description":"画布归属键，格式 canvas:{brand}:{userId}:{canvasId}:v1，服务端生成","type":"string"},"savedAt":{"description":"画布最近一次保存时间（RFC3339Nano）","type":"string"},"version":{"description":"画布文档结构版本号，当前为 1","type":"integer"},"viewport":{"description":"画布视口 {x, y, zoom}，zoom 为正数（点击展开查看详细字段）","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，正数","type":"number"}},"type":"object"}},"type":"object"},"revision":{"description":"画布版本号，每次成功变更自增，用作乐观锁；下次 apply/delete 需回传该值","type":"integer"},"updated_at":{"description":"最后更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"画布归属用户 ID，通常由网关按 API Key 注入；响应中可能省略","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"克隆画布分享","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/share/create":{"post":{"description":"为画布生成公开分享链接（/c/{token}），任何人可通过链接只读查看。分享快照是画布当前内容的冻结副本——画布本身无版本历史，快照同时是重要节点的备份恢复点（配合「克隆画布分享」恢复）。重复调用会刷新快照内容，token 保持不变。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-share-create","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"为一张画布创建（或复用已有）分享链接的请求","properties":{"canvas_id":{"description":"要分享的画布 ID，必填；画布须非空且素材已持久化，否则报错","type":"string"}},"required":["canvas_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"分享创建响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"share":{"description":"画布分享记录（点击展开查看详细字段）","properties":{"brand":{"description":"品牌标识","type":"string"},"canvas_id":{"description":"被分享的画布 ID","type":"string"},"created_at":{"description":"创建时间（RFC3339），可能省略","type":"string"},"id":{"description":"分享记录 ID，可能省略","type":"string"},"name":{"description":"分享时的画布名称快照","type":"string"},"revoked_at":{"description":"撤销时间（RFC3339），未撤销时缺省","type":"string"},"snapshot":{"description":"分享时的画布内容快照（与 payload 同结构，含 nodes/edges 等）（点击展开查看详细字段）","type":"object"},"status":{"description":"分享状态：active（有效）/ revoked（已撤销）","type":"string"},"token":{"description":"分享令牌，用于 share/view 查看或 share/clone 克隆","type":"string"},"updated_at":{"description":"更新时间（RFC3339），可能省略","type":"string"},"user_id":{"description":"分享创建者用户 ID，可能省略","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"创建画布分享","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.write"}},"/open/v1/canvas/share/view":{"post":{"description":"按分享 token 读取分享快照内容（节点/边/布局 + 素材临时访问 URL）。可读取任何人创建的有效分享，用于查看他人分享的画布或核对自己快照的冻结内容。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-share-view","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"按分享令牌查看画布公开视图的请求","properties":{"token":{"description":"分享令牌，来自 share/create 响应的 token，必填；无需登录即可查看","type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"分享查看响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"share":{"description":"画布公开视图；令牌无效或已撤销时报错（点击展开查看详细字段）","properties":{"asset_urls":{"description":"素材运行时签名 URL 映射，key 为节点 ID（无则为 bucket/key），value 为可直接访问的预签名 URL；仅运行时使用（点击展开查看详细字段）","type":"object"},"created_at":{"description":"分享创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"snapshot":{"description":"已脱敏的画布快照，去除了 ownerKey 及所有运行时 URL 字段（点击展开查看详细字段）","type":"object"},"token":{"description":"分享令牌","type":"string"},"updated_at":{"description":"分享更新时间（RFC3339），可能省略","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查看画布分享","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/canvas/tasks/batch-detail":{"post":{"description":"批量查询生成任务状态，用于画布多节点并行生成时的轮询。仅返回属于当前用户的任务，非本人任务 ID 会被静默过滤。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-tasks-batch-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"批量查询异步任务详情的请求","properties":{"task_ids":{"description":"任务 ID 列表，必填；一次批量查询多个任务详情","items":{"description":"任务 ID","type":"string"},"type":"array"}},"required":["task_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"批量任务详情响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"tasks":{"description":"任务详情列表，与请求 task_ids 对应","items":{"description":"异步任务详情（点击展开查看详细字段）","properties":{"blocking":{"description":"是否为阻塞型任务","type":"boolean"},"completed_at":{"description":"完成时间（Unix 秒）","type":"integer"},"consumed":{"description":"结果是否已被消费","type":"boolean"},"created_at":{"description":"创建时间（Unix 秒）","type":"integer"},"display_name":{"description":"任务展示名","type":"string"},"error":{"description":"失败原因，仅 failed 时有值","type":"string"},"expires_at":{"description":"结果过期时间（Unix 秒）","type":"integer"},"external_task_id":{"description":"下游生成服务外部任务 ID","type":"string"},"id":{"description":"任务 ID","type":"string"},"inject_count":{"description":"结果注入次数","type":"integer"},"last_poll_at":{"description":"上次轮询时间（Unix 秒）","type":"integer"},"max_polls":{"description":"最大轮询次数","type":"integer"},"max_retries":{"description":"最大重试次数","type":"integer"},"next_poll_at":{"description":"下次轮询时间（Unix 秒）","type":"integer"},"poll_count":{"description":"已轮询次数","type":"integer"},"progress":{"description":"任务进度，0~1","type":"number"},"raw_result":{"description":"下游原始结果，JSON 字符串（需二次解析）","type":"string"},"result":{"description":"任务结果，JSON 字符串（需二次解析）；结果中的素材 os_key 已被加签为可直接访问的 URL","type":"string"},"result_type":{"description":"结果类型标识","type":"string"},"retry_count":{"description":"已重试次数","type":"integer"},"session_id":{"description":"所属会话 ID","type":"string"},"status":{"description":"任务状态：pending / running / completed / failed / cancelled","type":"string"},"submitted_at":{"description":"提交时间（Unix 秒）","type":"integer"},"tool_name":{"description":"生成工具名，如 submit_image_generation","type":"string"},"tool_params":{"description":"任务入参，JSON 字符串（需二次解析）；其中素材引用的 os_key 已被服务端加签为可展示 URL","type":"string"},"updated_at":{"description":"更新时间（Unix 秒）","type":"integer"},"user_id":{"description":"任务归属用户 ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"生成任务批量详情","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/canvas/tasks/detail":{"post":{"description":"查询单个生成任务的状态与结果（含产物的对象存储坐标与临时访问 URL）。仅任务所有者可查，非本人返回 404。任务失败会自动退还冻结的出海贝。\n\nAI 画布 API 面向 Agent 程序化操作画布设计，需要出海匠企业版。画布接口本身调用免费，AI 生图/生视频等生成任务按出海贝计费。","operationId":"chuhaijiang-canvas-tasks-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"查询单个异步任务详情的请求","properties":{"task_id":{"description":"任务 ID，来自 submit 响应的 task_id，必填","type":"string"}},"required":["task_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"单任务详情响应","properties":{"base_resp":{"description":"业务状态信封，标识本次调用的业务处理结果（点击展开查看详细字段）","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"task":{"description":"异步任务详情（点击展开查看详细字段）","properties":{"blocking":{"description":"是否为阻塞型任务","type":"boolean"},"completed_at":{"description":"完成时间（Unix 秒）","type":"integer"},"consumed":{"description":"结果是否已被消费","type":"boolean"},"created_at":{"description":"创建时间（Unix 秒）","type":"integer"},"display_name":{"description":"任务展示名","type":"string"},"error":{"description":"失败原因，仅 failed 时有值","type":"string"},"expires_at":{"description":"结果过期时间（Unix 秒）","type":"integer"},"external_task_id":{"description":"下游生成服务外部任务 ID","type":"string"},"id":{"description":"任务 ID","type":"string"},"inject_count":{"description":"结果注入次数","type":"integer"},"last_poll_at":{"description":"上次轮询时间（Unix 秒）","type":"integer"},"max_polls":{"description":"最大轮询次数","type":"integer"},"max_retries":{"description":"最大重试次数","type":"integer"},"next_poll_at":{"description":"下次轮询时间（Unix 秒）","type":"integer"},"poll_count":{"description":"已轮询次数","type":"integer"},"progress":{"description":"任务进度，0~1","type":"number"},"raw_result":{"description":"下游原始结果，JSON 字符串（需二次解析）","type":"string"},"result":{"description":"任务结果，JSON 字符串（需二次解析）；结果中的素材 os_key 已被加签为可直接访问的 URL","type":"string"},"result_type":{"description":"结果类型标识","type":"string"},"retry_count":{"description":"已重试次数","type":"integer"},"session_id":{"description":"所属会话 ID","type":"string"},"status":{"description":"任务状态：pending / running / completed / failed / cancelled","type":"string"},"submitted_at":{"description":"提交时间（Unix 秒）","type":"integer"},"tool_name":{"description":"生成工具名，如 submit_image_generation","type":"string"},"tool_params":{"description":"任务入参，JSON 字符串（需二次解析）；其中素材引用的 os_key 已被服务端加签为可展示 URL","type":"string"},"updated_at":{"description":"更新时间（Unix 秒）","type":"integer"},"user_id":{"description":"任务归属用户 ID","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"生成任务详情","tags":["内容制作/5.AI 画布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.canvas.read"}},"/open/v1/creatives/search":{"get":{"description":"搜索 TikTok 广告素材/视频创意，支持按分类、地区、AIGC 等条件筛选和排序","operationId":"chuhaijiang-creatives-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"素材分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"是否关联商品","example":true,"in":"query","name":"has_product","required":false,"schema":{"type":"boolean"}},{"description":"是否为赞助内容","example":false,"in":"query","name":"is_sponsored","required":false,"schema":{"type":"boolean"}},{"description":"是否为AI生成内容","example":false,"in":"query","name":"is_aigc","required":false,"schema":{"type":"boolean"}},{"description":"排序，格式: field:asc|desc。支持: engagement, gmv, gpm, likes, plays。默认: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["engagement","gmv","gpm","likes","plays"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"author_nickname":{"description":"作者昵称","type":"string"},"author_uid":{"description":"作者用户ID","type":"string"},"author_unique_id":{"description":"作者TikTok用户名","type":"string"},"content_intent":{"description":"内容意图","type":"string"},"content_tag_v2":{"description":"内容标签","items":{"type":"string"},"type":"array"},"country_code":{"description":"国家代码","type":"string"},"follower_cnt":{"description":"粉丝数","type":"integer"},"id":{"description":"唯一标识","type":"string"},"is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"platform":{"description":"平台","type":"string"},"product_id":{"description":"商品ID","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"近30天视频GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_collect_count":{"description":"收藏数","type":"integer"},"video_comment_count":{"description":"评论数","type":"integer"},"video_date":{"description":"视频日期","type":"string"},"video_desc":{"description":"视频描述","type":"string"},"video_duration":{"description":"视频时长(ms)","type":"integer"},"video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"video_gmv":{"description":"视频GMV","type":"string"},"video_id":{"description":"视频ID","type":"string"},"video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"video_like_count":{"description":"点赞数","type":"integer"},"video_play_count":{"description":"播放量","type":"integer"},"video_share_count":{"description":"分享数","type":"integer"},"video_total_gmv":{"description":"视频总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_total_gpm":{"description":"视频总GPM","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"素材搜索","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creative.read"}},"/open/v1/creatives/{id}":{"get":{"description":"获取 TikTok 创意素材详情，含视频数据、创作者、关联商品，可选内容分析和向量嵌入","operationId":"chuhaijiang-creative-detail","parameters":[{"description":"素材视频ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"地区代码","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","de","fr","it","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"包含的子资源，逗号分隔：analysis,embedding","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: analysis(分析数据), embedding(向量数据)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","type":"number"},"country_code":{"description":"国家代码","type":"string"},"floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"follower_count":{"description":"粉丝数","type":"integer"},"id":{"description":"唯一标识","type":"string"},"l1_category":{"description":"一级类目","type":"string"},"l2_category":{"description":"二级类目","type":"string"},"l3_category":{"description":"三级类目","type":"string"},"nickname":{"description":"昵称","type":"string"},"product_country_code":{"description":"商品所在国家","type":"string"},"product_id":{"description":"商品ID","type":"string"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"product_launch_time":{"description":"商品上架时间(ms时间戳)","type":"integer"},"product_name":{"description":"商品名称","type":"string"},"product_rating":{"description":"商品评分(0-5)","type":"number"},"product_status":{"description":"商品状态","type":"integer"},"product_total_gmv":{"description":"商品总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_total_sold_count":{"description":"商品总销量","type":"integer"},"share_url":{"description":"TikTok分享链接","type":"string"},"uid":{"description":"用户ID","type":"string"},"unique_id":{"description":"TikTok用户名","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"近30天视频GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_30d_sold_count":{"description":"近30天视频带货销量","type":"integer"},"video_collect_count":{"description":"收藏数","type":"integer"},"video_comment_count":{"description":"评论数","type":"integer"},"video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"video_id":{"description":"视频ID","type":"string"},"video_like_count":{"description":"点赞数","type":"integer"},"video_play_count":{"description":"播放量","type":"integer"},"video_share_count":{"description":"分享数","type":"integer"},"video_total_gmv":{"description":"视频总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"素材详情","tags":["数据查询/5.广告与创意情报"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.creative.read"}},"/open/v1/creators/rankings/agencies":{"get":{"description":"查询 TikTok 达人机构的 30 日销售额、销量和关联资源表现。","operationId":"chuhaijiang-creators-ranking-agencies","parameters":[{"description":"机构主营商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：avg_commission_rate, creator_count, follower_count, gmv_30d, product_count, seller_count, sold_count_30d, video_count","example":"gmv_30d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_30d:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人机构榜","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/rankings/commercial":{"get":{"description":"按统计周期查询视频和直播带货表现领先的 TikTok 达人。","operationId":"chuhaijiang-creators-ranking-commercial","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"达人内容品类 ID","in":"query","name":"creator_category","required":false,"schema":{"type":"string"}},{"description":"达人带货一级商品品类 ID","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：live_gmv, live_user_count, product_count, total_gmv, video_gmv, video_play_growth","example":"total_gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"total_gmv:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"带货达人榜","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/rankings/growth":{"get":{"description":"按统计周期查询涨粉表现领先的 TikTok 达人。","operationId":"chuhaijiang-creators-ranking-growth","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"达人内容品类 ID","in":"query","name":"creator_category","required":false,"schema":{"type":"string"}},{"description":"达人带货商品品类 ID","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：follower_count, new_follower_count, new_follower_rate, video_count","example":"new_follower_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"new_follower_count:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人涨粉榜","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/search":{"get":{"description":"搜索 TikTok 达人，支持粉丝数、GMV、互动率等多维度过滤","operationId":"chuhaijiang-creators-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"达人分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"最少粉丝数","example":10000,"in":"query","name":"min_followers","required":false,"schema":{"type":"number"}},{"description":"最多粉丝数","example":1000000,"in":"query","name":"max_followers","required":false,"schema":{"type":"number"}},{"description":"30天最低GMV（美元）","example":1000,"in":"query","name":"min_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"30天最高GMV（美元）","example":100000,"in":"query","name":"max_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"最低平均播放量","example":1000,"in":"query","name":"min_avg_views","required":false,"schema":{"type":"number"}},{"description":"最高平均播放量","example":100000,"in":"query","name":"max_avg_views","required":false,"schema":{"type":"number"}},{"description":"最低互动率（0-1）","example":0.01,"in":"query","name":"min_engagement","required":false,"schema":{"type":"number"}},{"description":"最高互动率（0-1）","example":0.1,"in":"query","name":"max_engagement","required":false,"schema":{"type":"number"}},{"description":"是否有联系方式","example":true,"in":"query","name":"has_contact","required":false,"schema":{"type":"boolean"}},{"description":"排序，格式: field:asc|desc。支持: avg_views, engagement, follower_growth_7d, followers, gmv_30d, video_gmv_30d。默认: gmv_30d:desc","example":"gmv_30d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_30d:desc","enum":["avg_views","engagement","follower_growth_7d","followers","gmv_30d","video_gmv_30d"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"账号类型","type":"integer"},"author_avg_engagement_rate":{"description":"平均互动率(0-1)","type":"number"},"bio_email":{"description":"简介邮箱","type":"string"},"category_label":{"description":"达人分类标签","type":"string"},"country_code":{"description":"国家代码","type":"string"},"ecom_video_avg_play_count":{"description":"电商视频平均播放量","type":"number"},"facebook_url":{"description":"Facebook链接","type":"string"},"follower_count":{"description":"粉丝数","type":"integer"},"follower_count_growth_for_last_7_days":{"description":"近7天涨粉数","type":"integer"},"has_live_product":{"description":"是否有直播带货","type":"boolean"},"has_shop_product":{"description":"是否有店铺商品","type":"boolean"},"has_video_product":{"description":"是否有视频带货","type":"boolean"},"id":{"description":"唯一标识","type":"string"},"ins_id":{"description":"Instagram账号","type":"string"},"linkedin_url":{"description":"LinkedIn链接","type":"string"},"live_30d_gmv":{"description":"近30天直播GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"live_30d_gpm":{"description":"近30天直播GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"nickname":{"description":"昵称","type":"string"},"product_category_label_list":{"description":"商品分类标签列表","items":{"type":"string"},"type":"array"},"telegram_url":{"description":"Telegram链接","type":"string"},"total_favorited":{"description":"总获赞数","type":"integer"},"total_video_live_30d_gmv":{"description":"近30天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"twitter_id":{"description":"Twitter/X账号","type":"string"},"unique_id":{"description":"TikTok用户名","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"user_sell_product_l3_category":{"description":"售卖商品三级类目列表","items":{"type":"string"},"type":"array"},"video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_30d_gpm":{"description":"近30天视频GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_avg_like_count":{"description":"视频平均点赞数","type":"number"},"video_avg_play_count":{"description":"视频平均播放量","type":"number"},"video_total_like_count_to_follower_count_ratio":{"description":"总点赞数/粉丝数比值","type":"number"},"whatsapp_url":{"description":"WhatsApp链接","type":"string"},"youtube_channel_id":{"description":"YouTube频道ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人搜索","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/{id}":{"get":{"description":"获取 TikTok 达人详情，含视频列表、带货商品","operationId":"chuhaijiang-creators-detail","parameters":[{"description":"达人ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: channel(销售渠道), core(核心指标), portrait(粉丝画像)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"bio_email":{"description":"简介邮箱","type":"string"},"bio_url":{"description":"个人主页链接","type":"string"},"category_label":{"description":"达人分类标签","type":"string"},"enterprise_verify_reason":{"description":"企业认证描述","type":"string"},"facebook_url":{"description":"Facebook链接","type":"string"},"has_live_product":{"description":"是否有直播带货","type":"boolean"},"has_shop_product":{"description":"是否有店铺商品","type":"boolean"},"has_video_product":{"description":"是否有视频带货","type":"boolean"},"id":{"description":"唯一标识","type":"string"},"ins_id":{"description":"Instagram账号","type":"string"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"linkedin_url":{"description":"LinkedIn链接","type":"string"},"nickname":{"description":"昵称","type":"string"},"partnered_brand":{"description":"合作品牌","items":{"properties":{"id":{"description":"品牌ID","type":"string"},"name":{"description":"品牌名称","type":"string"}},"type":"object"},"type":"array"},"product_category_label_list":{"description":"商品分类标签列表","items":{"type":"string"},"type":"array"},"seller_avatar":{"description":"店铺头像","type":"string"},"shop_main_category":{"description":"店铺主营类目","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"shop_rating":{"description":"店铺评分","type":"string"},"signature":{"description":"个人简介","type":"string"},"telegram_url":{"description":"Telegram链接","type":"string"},"total_gmv":{"description":"总GMV","type":"string"},"total_sold_count":{"description":"总销售量","type":"string"},"twitter_id":{"description":"Twitter/X账号","type":"string"},"unique_id":{"description":"TikTok 用户名","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"website":{"description":"个人网站","type":"string"},"wechat":{"description":"微信号","type":"string"},"whatsapp_url":{"description":"WhatsApp链接","type":"string"},"youtube_channel_id":{"description":"YouTube频道ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人详情","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/{id}/lives":{"get":{"description":"","operationId":"chuhaijiang-creators-lives","parameters":[{"description":"达人ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_creator_detail_live_country_code":{"description":"国家代码","type":"string"},"tiktok_creator_detail_live_cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_creator_detail_live_end_time":{"description":"结束时间(ms时间戳)","type":"integer"},"tiktok_creator_detail_live_gmv":{"description":"GMV(成交总额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_live_gpm":{"description":"GPM(千次观看成交额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_live_max_user_count":{"description":"最高在线人数","type":"integer"},"tiktok_creator_detail_live_most_product_category_label":{"description":"主要商品分类","type":"string"},"tiktok_creator_detail_live_new_follow_count":{"description":"新增粉丝数","type":"integer"},"tiktok_creator_detail_live_opm":{"description":"OPM(千次观看订单数)","type":"number"},"tiktok_creator_detail_live_product_count":{"description":"商品数量","type":"integer"},"tiktok_creator_detail_live_room_id":{"description":"直播间ID","type":"string"},"tiktok_creator_detail_live_room_link":{"description":"直播间链接","type":"string"},"tiktok_creator_detail_live_start_time":{"description":"开始时间(ms时间戳)","type":"integer"},"tiktok_creator_detail_live_title":{"description":"直播标题","type":"string"},"tiktok_creator_detail_live_total_sold_count":{"description":"总销售量","type":"integer"},"tiktok_creator_detail_live_total_user":{"description":"总观看人数","type":"integer"},"tiktok_creator_detail_live_user_follower_count":{"description":"用户粉丝数","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人关联直播","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/{id}/products":{"get":{"description":"","operationId":"chuhaijiang-creators-products","parameters":[{"description":"达人ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_creator_detail_by_live":{"description":"是否通过直播带货","type":"boolean"},"tiktok_creator_detail_by_shop":{"description":"是否通过店铺售卖","type":"boolean"},"tiktok_creator_detail_by_video":{"description":"是否通过视频带货","type":"boolean"},"tiktok_creator_detail_live_30d_gmv":{"description":"近30天GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_live_30d_sold_count":{"description":"近30天销量","type":"integer"},"tiktok_creator_detail_product_country_code":{"description":"商品所在国家","type":"string"},"tiktok_creator_detail_product_id":{"description":"商品ID","type":"string"},"tiktok_creator_detail_product_launch_time":{"description":"商品上架时间(ms时间戳)","type":"integer"},"tiktok_creator_detail_total_video_live_30d_gmv":{"description":"近30天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_total_video_live_30d_sold_count":{"description":"近30天视频+直播总销量","type":"integer"},"tiktok_creator_detail_user_id":{"description":"用户ID","type":"string"},"tiktok_creator_detail_video_30d_gmv":{"description":"近30天GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_video_30d_sold_count":{"description":"近30天销量","type":"integer"},"tiktok_product_detail_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"佣金率","type":"string"},"tiktok_product_detail_floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"一级类目","type":"string"},"tiktok_product_detail_l2_category":{"description":"二级类目","type":"string"},"tiktok_product_detail_l3_category":{"description":"三级类目","type":"string"},"tiktok_product_detail_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"商品名称","type":"string"},"tiktok_product_detail_product_rating":{"description":"商品评分(0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU属性","items":{"properties":{"has_image":{"description":"是否有图片","type":"boolean"},"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名","type":"string"},"sale_prop_values":{"description":"属性值列表","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU列表","items":{"properties":{"is_hot":{"description":"是否热销","type":"boolean"},"price":{"properties":{"discount":{"description":"折扣信息","type":"string"},"original_price":{"description":"原价","type":"string"},"original_price_value":{"description":"原价数值","type":"string"},"real_price":{"description":"实际价格","type":"number"},"unit_price_desc":{"description":"单价描述","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"属性值ID组合","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU属性","items":{"properties":{"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名(如Color)","type":"string"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"状态(1=在售)","type":"integer"},"stock":{"description":"库存","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"商品状态","type":"integer"},"tiktok_product_detail_region":{"description":"地区代码","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人带货商品","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/{id}/similar":{"get":{"description":"","operationId":"chuhaijiang-creators-similar","parameters":[{"description":"达人ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_creator_detail_similar_category_label":{"description":"达人分类标签","type":"string"},"tiktok_creator_detail_similar_country_code":{"description":"国家代码","type":"string"},"tiktok_creator_detail_similar_follower_count":{"description":"粉丝数","type":"integer"},"tiktok_creator_detail_similar_nickname":{"description":"昵称","type":"string"},"tiktok_creator_detail_similar_total_video_live_30d_gmv":{"description":"近30天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_similar_uid":{"description":"用户ID","type":"string"},"tiktok_creator_detail_similar_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"相似达人","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/creators/{id}/videos":{"get":{"description":"","operationId":"chuhaijiang-creators-videos","parameters":[{"description":"达人ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_creator_detail_is_ad":{"description":"是否广告投放","type":"boolean"},"tiktok_creator_detail_is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"tiktok_creator_detail_video_30d_gmv":{"description":"近30天GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_creator_detail_video_30d_sold_count":{"description":"近30天销量","type":"integer"},"tiktok_creator_detail_video_ad_source":{"description":"广告来源(1=有)","type":"string"},"tiktok_creator_detail_video_author_category_label":{"description":"作者分类标签","type":"string"},"tiktok_creator_detail_video_author_nickname":{"description":"作者昵称","type":"string"},"tiktok_creator_detail_video_author_uid":{"description":"作者用户ID","type":"string"},"tiktok_creator_detail_video_author_unique_id":{"description":"作者TikTok用户名","type":"string"},"tiktok_creator_detail_video_collect_count":{"description":"收藏数","type":"integer"},"tiktok_creator_detail_video_comment_count":{"description":"评论数","type":"integer"},"tiktok_creator_detail_video_country_code":{"description":"国家代码","type":"string"},"tiktok_creator_detail_video_cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_creator_detail_video_desc":{"description":"描述","type":"string"},"tiktok_creator_detail_video_duration":{"description":"时长(ms)","type":"integer"},"tiktok_creator_detail_video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"tiktok_creator_detail_video_id":{"description":"唯一标识","type":"string"},"tiktok_creator_detail_video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"tiktok_creator_detail_video_like_count":{"description":"点赞数","type":"integer"},"tiktok_creator_detail_video_play_count":{"description":"播放量","type":"integer"},"tiktok_creator_detail_video_product_id":{"description":"商品ID","type":"string"},"tiktok_creator_detail_video_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_creator_detail_video_product_l1_category":{"description":"商品一级类目","type":"string"},"tiktok_creator_detail_video_product_l2_category":{"description":"商品二级类目","type":"string"},"tiktok_creator_detail_video_product_l3_category":{"description":"商品三级类目","type":"string"},"tiktok_creator_detail_video_product_title":{"description":"商品标题","type":"string"},"tiktok_creator_detail_video_share_count":{"description":"分享数","type":"integer"},"tiktok_creator_detail_video_share_url":{"description":"TikTok分享链接","type":"string"},"tiktok_creator_detail_video_total_like_count_to_follower_count_ratio":{"description":"总点赞数/粉丝数比值","type":"number"},"tiktok_creator_detail_video_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"达人视频列表","tags":["数据查询/2.达人数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.creators.read"}},"/open/v1/dashboards/categories/heatmap":{"get":{"description":"查询品类销售额、销量、增长率和蓝海指数热力图。","operationId":"chuhaijiang-dashboards-categories-heatmap","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"热力图容器","items":{"properties":{"graph":{"description":"品类热力图树","items":{"additionalProperties":true,"properties":{"category_data":{"description":"品类指标（点击展开查看详细字段）","properties":{"interval_blue_ocean_index":{"description":"蓝海指数","type":"number"},"interval_product_count":{"description":"动销商品数","type":"number"},"interval_product_gmv":{"description":"销售额","type":"number"},"interval_product_gmv_growth_rate":{"description":"销售额增长率","type":"number"},"interval_product_sold_count":{"description":"销量","type":"number"},"interval_product_sold_count_growth_rate":{"description":"销量增长率","type":"number"}},"type":"object"},"category_label":{"description":"品类 ID","type":"string"},"children":{"description":"子品类节点","items":{"additionalProperties":true,"type":"object"},"type":"array"},"parent_category":{"description":"父品类 ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"total_count":{"description":"容器记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"品类热力图","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/dashboards/categories/metrics":{"get":{"description":"查询品类大盘的销售额、销量、动销商品数、平均价格和带货达人数。","operationId":"chuhaijiang-dashboards-categories-metrics","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":4}},"schema":{"properties":{"data":{"properties":{"items":{"description":"核心指标结果，通常为一条","items":{"properties":{"core_category_label":{"description":"品类 ID；未筛选时为 all_category","type":"string"},"interval_avg_product_price":{"description":"平均商品价格（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_product_count":{"description":"动销商品数","type":"number"},"interval_product_gmv":{"description":"销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"销量","type":"number"},"interval_total_related_creator_count":{"description":"关联带货达人数","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"结果数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"品类核心指标","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":4,"x-scope":"chuhaijiang.products.read"}},"/open/v1/dashboards/products/category-share":{"post":{"description":"查询商品大盘中各品类销售额及其占比。","operationId":"chuhaijiang-dashboards-products-category-share","parameters":[{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"榜单或大盘查询条件（点击展开查看详细字段）","properties":{"field_filter":{"description":"业务筛选条件。可用父品类键：tiktok_product_dashboard_category；不传时返回顶层品类。","items":{"description":"单个筛选条件（点击展开查看详细字段）","properties":{"exclude_values":{"description":"排除值列表","items":{"type":"string"},"type":"array"},"filter_key":{"description":"hertz_data 筛选字段键","type":"string"},"include_values":{"description":"包含值列表","items":{"type":"string"},"type":"array"},"left_date_time":{"description":"日期范围下界，通常为 YYYYMMDD","type":"string"},"left_value":{"description":"数值范围下界","type":"number"},"quick_option_name":{"description":"快捷选项值，如品类 ID 或店铺类型选项","type":"string"},"right_date_time":{"description":"日期范围上界，通常为 YYYYMMDD","type":"string"},"right_value":{"description":"数值范围上界","type":"number"},"value":{"description":"精确匹配值","type":"string"}},"required":["filter_key"],"type":"object"},"type":"array"},"time_filter":{"description":"统计周期（点击展开查看详细字段）","properties":{"end_date_time":{"description":"自定义时间范围结束日期，格式 YYYYMMDD","pattern":"^\\d{8}$","type":"string"},"granularity":{"description":"时间粒度：0=日，1=周，2=月","enum":[0,1,2],"example":0,"type":"integer"},"is_customized":{"description":"是否使用自定义时间范围","type":"boolean"},"start_date_time":{"description":"统计日期，格式 YYYYMMDD","example":"20260803","pattern":"^\\d{8}$","type":"string"}},"required":["granularity","start_date_time"],"type":"object"}},"required":["time_filter"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":4}},"schema":{"properties":{"data":{"properties":{"filter_list":{"description":"品类销售额分布","items":{"properties":{"filter_key":{"description":"筛选字段键","type":"string"},"quick_option_list":{"description":"品类列表","items":{"additionalProperties":true,"properties":{"children":{"description":"子品类分布","items":{"additionalProperties":true,"type":"object"},"type":"array"},"distribute":{"description":"销售额及占比（点击展开查看详细字段）","properties":{"percentage":{"description":"品类销售额占比","type":"string"},"value":{"description":"品类销售额","type":"number"}},"type":"object"},"option_id":{"description":"品类 ID","type":"string"},"option_name":{"description":"品类名称或 ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品品类销售额占比","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":4,"x-scope":"chuhaijiang.products.read"}},"/open/v1/dashboards/products/metrics":{"get":{"description":"查询商品大盘的销售额、销量、动销商品数、平均价格和带货达人数。","operationId":"chuhaijiang-dashboards-products-metrics","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"商品品类 ID；不传时返回全部品类核心指标","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":4}},"schema":{"properties":{"data":{"properties":{"items":{"description":"核心指标结果，通常为一条","items":{"properties":{"core_category_label":{"description":"品类 ID；未筛选时为 all_category","type":"string"},"interval_avg_product_price":{"description":"平均商品价格（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_product_count":{"description":"动销商品数","type":"number"},"interval_product_gmv":{"description":"销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"销量","type":"number"},"interval_total_related_creator_count":{"description":"关联带货达人数","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"结果数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品核心指标","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":4,"x-scope":"chuhaijiang.products.read"}},"/open/v1/dashboards/sellers/concentration":{"get":{"description":"查询全部、本土、跨境和全托管类型的头部店铺及集中度占比。","operationId":"chuhaijiang-dashboards-sellers-concentration","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"商品品类 ID；不传时返回全部店铺集中度","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"店铺集中度结果，通常为一条","items":{"properties":{"all_type_seller_list":{"description":"头部店铺列表","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"集中度占比","type":"number"},"interval_seller_gmv":{"description":"周期销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"周期销量","type":"number"},"rn":{"description":"排名","type":"number"},"seller_id":{"description":"店铺 ID","type":"string"}},"type":"object"},"type":"array"},"category_label":{"description":"品类 ID","type":"string"},"local_seller_list":{"description":"头部店铺列表","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"集中度占比","type":"number"},"interval_seller_gmv":{"description":"周期销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"周期销量","type":"number"},"rn":{"description":"排名","type":"number"},"seller_id":{"description":"店铺 ID","type":"string"}},"type":"object"},"type":"array"},"managed_seller_list":{"description":"头部店铺列表","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"集中度占比","type":"number"},"interval_seller_gmv":{"description":"周期销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"周期销量","type":"number"},"rn":{"description":"排名","type":"number"},"seller_id":{"description":"店铺 ID","type":"string"}},"type":"object"},"type":"array"},"overseas_seller_list":{"description":"头部店铺列表","items":{"additionalProperties":true,"properties":{"concentration_ratio":{"description":"集中度占比","type":"number"},"interval_seller_gmv":{"description":"周期销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_seller_sold_count":{"description":"周期销量","type":"number"},"rn":{"description":"排名","type":"number"},"seller_id":{"description":"店铺 ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"total_count":{"description":"结果数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺集中度","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/dashboards/sellers/metrics":{"get":{"description":"查询店铺数、店均销售额及本土、跨境、全托管店铺销售额占比。","operationId":"chuhaijiang-dashboards-sellers-metrics","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"商品品类 ID；不传时返回全部店铺核心指标","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":4}},"schema":{"properties":{"data":{"properties":{"items":{"description":"店铺核心指标，通常为一条","items":{"properties":{"category_label":{"description":"品类 ID","type":"string"},"interval_avg_seller_gmv":{"description":"店均销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_local_shop_rate":{"description":"本土店销售额占比","type":"number"},"interval_managed_shop_rate":{"description":"全托管店销售额占比","type":"number"},"interval_overseas_shop_rate":{"description":"跨境店销售额占比","type":"number"},"interval_product_gmv":{"description":"商品销售额（点击展开查看详细字段）","properties":{"unit":{"description":"货币或市场单位","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_product_sold_count":{"description":"商品销量","type":"number"},"interval_seller_count":{"description":"动销店铺数","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"结果数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺核心指标","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":4,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/lives/search":{"get":{"description":"搜索 TikTok 带货直播，支持销量、GMV、观众数等过滤","operationId":"chuhaijiang-lives-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"主播分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"商品分类ID","example":"100001","in":"query","name":"product_category","required":false,"schema":{"type":"string"}},{"description":"是否正在直播","example":false,"in":"query","name":"is_living","required":false,"schema":{"type":"boolean"}},{"description":"是否为带货直播","example":false,"in":"query","name":"is_commercial","required":false,"schema":{"type":"boolean"}},{"description":"最低销量","example":100,"in":"query","name":"min_sold","required":false,"schema":{"type":"number"}},{"description":"最高销量","example":10000,"in":"query","name":"max_sold","required":false,"schema":{"type":"number"}},{"description":"最低GMV（美元）","example":1000,"in":"query","name":"min_gmv","required":false,"schema":{"type":"number"}},{"description":"最高GMV（美元）","example":100000,"in":"query","name":"max_gmv","required":false,"schema":{"type":"number"}},{"description":"最低观众数","example":100,"in":"query","name":"min_audience","required":false,"schema":{"type":"number"}},{"description":"最高观众数","example":100000,"in":"query","name":"max_audience","required":false,"schema":{"type":"number"}},{"description":"排序，格式: field:asc|desc。支持: audience, gmv, peak_audience, sold, start_time。默认: gmv:desc","example":"gmv:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv:desc","enum":["audience","gmv","peak_audience","sold","start_time"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"country_code":{"description":"国家代码","type":"string"},"cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"end_time":{"description":"结束时间(ms时间戳)","type":"integer"},"gmv":{"description":"GMV(成交总额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"gpm":{"description":"GPM(千次观看成交额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"id":{"description":"唯一标识","type":"string"},"max_user_count":{"description":"最高在线人数","type":"integer"},"most_product_category_label":{"description":"主要商品分类","type":"string"},"new_follow_count":{"description":"新增粉丝数","type":"integer"},"opm":{"description":"OPM(千次观看订单数)","type":"number"},"product_count":{"description":"商品数量","type":"integer"},"room_link":{"description":"直播间链接","type":"string"},"start_time":{"description":"开始时间(ms时间戳)","type":"integer"},"title":{"description":"直播标题","type":"string"},"total_sold_count":{"description":"总销售量","type":"integer"},"total_user":{"description":"总观看人数","type":"integer"},"user_category_label":{"description":"用户分类标签","type":"string"},"user_id":{"description":"用户ID","type":"string"},"user_nickname":{"description":"用户昵称","type":"string"},"user_unique_id":{"description":"用户TikTok用户名","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"直播搜索","tags":["数据查询/6.直播数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.lives.read"}},"/open/v1/lives/{id}":{"get":{"description":"获取 TikTok 直播详情，包括基础信息、核心指标、趋势、关联商品、相似直播","operationId":"chuhaijiang-lives-detail","parameters":[{"description":"直播ID","in":"path","name":"entity_id","required":true,"schema":{"type":"string"}},{"description":"地区代码","in":"query","name":"country","required":true,"schema":{"enum":["us","th","my","vn","mx","it","fr","de","es","jp","br","gb","ph","sg","id"],"type":"string"}},{"description":"包含的子资源，逗号分隔：core,trend,products,similar","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: core(核心指标)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"country_code":{"description":"国家代码","type":"string"},"cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"end_time":{"description":"结束时间(ms时间戳)","type":"integer"},"id":{"description":"唯一标识","type":"string"},"most_product_category_label":{"description":"主要商品分类","type":"string"},"room_link":{"description":"直播间链接","type":"string"},"start_time":{"description":"开始时间(ms时间戳)","type":"integer"},"title":{"description":"直播标题","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"user_avg_audience_count":{"description":"平均观看人数","type":"number"},"user_avg_max_audience_count":{"description":"平均最高在线","type":"number"},"user_follower_count":{"description":"用户粉丝数","type":"integer"},"user_id":{"description":"用户ID","type":"string"},"user_live_count":{"description":"历史直播场次","type":"integer"},"user_nickname":{"description":"用户昵称","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"直播详情","tags":["数据查询/6.直播数据"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.lives.read"}},"/open/v1/lives/{id}/products":{"get":{"description":"","operationId":"chuhaijiang-lives-products","parameters":[{"description":"直播ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_live_detail_product_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_live_detail_product_commission_rate_num":{"description":"佣金率","type":"string"},"tiktok_live_detail_product_conversion_rate":{"description":"转化率","type":"number"},"tiktok_live_detail_product_country_code":{"description":"国家代码","type":"string"},"tiktok_live_detail_product_floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_live_detail_product_gmv":{"description":"GMV(成交总额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_live_detail_product_id":{"description":"唯一标识","type":"string"},"tiktok_live_detail_product_images":{"description":"图片列表","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_live_detail_product_l1_category":{"description":"一级类目","type":"string"},"tiktok_live_detail_product_l2_category":{"description":"二级类目","type":"string"},"tiktok_live_detail_product_l3_category":{"description":"三级类目","type":"string"},"tiktok_live_detail_product_rating":{"description":"评分","type":"string"},"tiktok_live_detail_product_seller_avatar":{"description":"店铺头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_live_detail_product_seller_category_name_label":{"description":"店铺类目标签","type":"string"},"tiktok_live_detail_product_seller_id":{"description":"店铺ID","type":"string"},"tiktok_live_detail_product_seller_info":{"description":"店铺信息","items":{"type":"string"},"type":"array"},"tiktok_live_detail_product_seller_name":{"description":"店铺名称","type":"string"},"tiktok_live_detail_product_sold_count":{"description":"销量","type":"integer"},"tiktok_live_detail_product_title":{"description":"直播标题","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"直播关联商品","tags":["数据查询/6.直播数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.lives.read"}},"/open/v1/lives/{id}/similar":{"get":{"description":"","operationId":"chuhaijiang-lives-similar","parameters":[{"description":"直播ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_live_detail_similar_country_code":{"description":"国家代码","type":"string"},"tiktok_live_detail_similar_cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_live_detail_similar_gmv":{"description":"GMV(成交总额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_live_detail_similar_max_user_count":{"description":"最高在线人数","type":"integer"},"tiktok_live_detail_similar_most_product_category_label":{"description":"主要商品分类","type":"string"},"tiktok_live_detail_similar_room_id":{"description":"直播间ID","type":"string"},"tiktok_live_detail_similar_title":{"description":"直播标题","type":"string"},"tiktok_live_detail_similar_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_live_detail_similar_user_id":{"description":"用户ID","type":"string"},"tiktok_live_detail_similar_user_nickname":{"description":"用户昵称","type":"string"},"tiktok_live_detail_similar_user_unique_id":{"description":"用户TikTok用户名","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"相似直播","tags":["数据查询/6.直播数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.lives.read"}},"/open/v1/products/amazon/detail":{"post":{"description":"按 ASIN 获取 Amazon 商品详情：本币价格与货币单位、BSR 畅销排名（大类+细分类）、近一月购买量、星级分布、卖点/描述/规格等。市场验证信息密度最高的一条。","operationId":"chuhaijiang-amazon-products-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"asin":{"description":"Amazon 商品 ID（ASIN，10 位字符，如 B0CP9YB3Q4），可从「Amazon 商品搜索」接口（数据查询/8.亚马逊数据 分组）的返回结果中获取","type":"string"},"marketplace":{"description":"Amazon 站点，枚举：us（美国）、uk（英国）、de（德国）、jp（日本），不传默认 us。注意站点码 uk 与本平台其他接口的 country 码 gb 不一致，勿混用；jp 站点可用性可能波动。","enum":["us","uk","de","jp"],"type":"string"}},"required":["asin"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"description":"商品详情完整字段（此处列关键字段，完整字段以实际响应为准）","properties":{"asin":{"description":"商品 ASIN","type":"string"},"availability":{"description":"库存状态（如 IN_STOCK）","type":"string"},"bought_past_month":{"description":"近一月购买量，如 \"9K+\"","type":"string"},"brand_name":{"description":"品牌名","type":"string"},"bsr":{"description":"大类畅销排名（Best Sellers Rank），可能为 null，非 us 站点尤其","type":"integer"},"bsr_category":{"description":"BSR 大类名称（如 Kitchen \u0026 Dining）","type":"string"},"bsr_sub_category":{"description":"BSR 细分类名称（如 Insulated Tumblers）","type":"string"},"bsr_sub_rank":{"description":"细分类畅销排名，可能为 null","type":"integer"},"bullet_points":{"description":"卖点列表","items":{"description":"单条卖点文本","type":"string"},"type":"array"},"category":{"description":"商品品类（如 Kitchen）","type":"string"},"currency":{"description":"货币单位（如 USD/GBP/EUR/JPY）","type":"string"},"description":{"description":"商品描述","type":"string"},"image_url":{"description":"商品主图 URL","type":"string"},"image_urls":{"description":"商品图片 URL 列表","items":{"description":"图片 URL","type":"string"},"type":"array"},"list_price":{"description":"划线价（本币字符串），无划线价时为 null","type":"string"},"price":{"description":"商品价格，所选站点本币金额的字符串（如 \"25.0\"）","type":"string"},"price_display":{"description":"带货币单位的展示价格（如 \"USD 25.0\"）","type":"string"},"rating":{"description":"商品评分（0-5）","type":"number"},"review_count":{"description":"评论总数","type":"integer"},"seller_name":{"description":"卖家名称（如 Amazon.com）","type":"string"},"specifications":{"description":"规格参数，两层嵌套键值对：第一层键为分组名（如 Measurements、Style、Materials \u0026 Care，随品类变化），第二层为该分组下的参数名→参数值（均为字符串）。分组与参数项随商品动态变化，不可枚举，示例：{\"Measurements\": {\"Capacity\": \"30 Fluid ounces\", \"Item Weight\": \"1.19 Pounds\"}}","type":"object"},"star_distribution":{"description":"各星级评论占比（百分比整数，五档合计约 100）。如 {\"5\": 87} 表示 5 星评论占 87%","properties":{"1":{"description":"1 星评论占比（%）","type":"integer"},"2":{"description":"2 星评论占比（%）","type":"integer"},"3":{"description":"3 星评论占比（%）","type":"integer"},"4":{"description":"4 星评论占比（%）","type":"integer"},"5":{"description":"5 星评论占比（%）","type":"integer"}},"type":"object"},"title":{"description":"商品标题（站点本地语言）","type":"string"},"variation_count":{"description":"变体（颜色/尺寸等）数量","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Amazon 商品详情","tags":["数据查询/7.亚马逊数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/amazon/reviews":{"post":{"description":"按 ASIN 获取 Amazon 商品的头部评论（约 8-10 条），含评分/正文/验证购买标记。用于消费者痛点提取与差异化卖点分析。","operationId":"chuhaijiang-amazon-products-reviews","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"asin":{"description":"Amazon 商品唯一标识（ASIN），从「Amazon 商品搜索」接口（数据查询/8.亚马逊数据 分组）的返回中获取","type":"string"},"marketplace":{"description":"Amazon 站点，枚举：us（美国）、uk（英国）、de（德国）、jp（日本），不传默认 us。注意站点码 uk 与本平台其他接口的 country 码 gb 不一致，勿混用；jp 站点可用性可能波动。","enum":["us","uk","de","jp"],"type":"string"}},"required":["asin"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"asin":{"description":"查询的商品 ASIN","type":"string"},"rating":{"description":"商品整体评分","type":"string"},"reviews":{"description":"头部评论列表，约 8-10 条（点击展开查看详细字段）","items":{"properties":{"author":{"description":"评论者昵称","type":"string"},"body":{"description":"评论正文，可用于消费者痛点提取","type":"string"},"date":{"description":"评论时间与地区描述","type":"string"},"helpful":{"description":"觉得有用的人数描述","type":"string"},"rating":{"description":"该条评论的评分（1-5）","type":"string"},"review_id":{"description":"评论唯一 ID","type":"string"},"title":{"description":"评论标题","type":"string"},"verified":{"description":"是否已验证购买（True/False）","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"评论总数","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Amazon 商品评论","tags":["数据查询/7.亚马逊数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/amazon/search":{"post":{"description":"按关键词搜索 Amazon 商品，返回标题/价格/评分/评论数等核心指标。用于 TikTok 选品的市场需求验证：评论量与评分是长期真实需求的直接证据。","operationId":"chuhaijiang-amazon-products-search","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"搜索关键词，如 tumbler、insulated water bottle","type":"string"},"marketplace":{"description":"Amazon 站点，枚举：us（美国）、uk（英国）、de（德国）、jp（日本），不传默认 us。注意站点码 uk 与本平台其他接口的 country 码 gb 不一致，勿混用；jp 站点可用性可能波动。","enum":["us","uk","de","jp"],"type":"string"},"page":{"description":"页码，从 1 开始，每页固定 10 条，不传默认 1","type":"integer"}},"required":["keyword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"count":{"description":"本页返回的商品条数","type":"integer"},"keyword":{"description":"实际搜索的关键词","type":"string"},"page":{"description":"当前页码","type":"integer"},"products":{"description":"商品列表（点击展开查看详细字段）","items":{"properties":{"asin":{"description":"Amazon 商品唯一标识（ASIN），可传给「Amazon 商品评论」接口（数据查询/8.亚马逊数据 分组）查询评论","type":"string"},"image_url":{"description":"商品主图 URL","type":"string"},"is_sponsored":{"description":"是否广告位（Sponsored）商品","type":"boolean"},"price":{"description":"商品价格，数值为所选站点的本币金额（us=美元，uk=英镑，de=欧元，jp=日元），响应不含货币单位字段，请按 marketplace 参数自行映射货币","type":"number"},"rating":{"description":"商品评分（0-5）","type":"number"},"review_count":{"description":"评论总数","type":"integer"},"title":{"description":"商品标题（站点本地语言）","type":"string"}},"type":"object"},"type":"array"},"total_results":{"description":"Amazon 侧估算的结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Amazon 商品搜索","tags":["数据查询/7.亚马逊数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/image-search":{"post":{"description":"上传商品图片，按图搜索 TikTok 相似商品。使用流程：先调用「（加速版）生成上传预签名URL」接口（在「文件上传」分类下）上传图片，拿到返回的 os_key，再将 os_key 传入本接口。返回视觉相似的商品列表（含商品名、一级类目、价格区间、销量、GMV）。","operationId":"chuhaijiang-products-image-search","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"country":{"description":"目标市场国家码（ISO 3166 alpha-2 大写），如 US/GB/ID。默认 US。","example":"US","type":"string"},"os_key":{"description":"图片对象存储路径。先调用「（加速版）生成上传预签名URL」接口（在「文件上传」分类下）上传图片，用返回的 os_key 传入。必填。","example":"upload/258a48a7_1784637533350345533.jpg","type":"string"}},"required":["os_key"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":20}},"schema":{"properties":{"data":{"properties":{"items":{"description":"视觉相似的商品列表","items":{"properties":{"ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"id":{"description":"商品唯一标识","type":"string"},"l1_category":{"description":"一级类目","type":"string"},"product_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_images":{"description":"商品图片URL列表","items":{"type":"string"},"type":"array"},"product_name":{"description":"商品名称","type":"string"},"product_sold_count":{"description":"销量","type":"integer"},"region":{"description":"地区代码","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"召回商品总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"图搜商品","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":20,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/rankings/most-promoted":{"get":{"description":"按统计周期查询达人、视频和直播集中推广的 TikTok 商品榜单。","operationId":"chuhaijiang-products-ranking-most-promoted","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"卖家类型：1=海外，2=本地，3=品牌，4=非品牌","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：interval_gmv, interval_sold_count, live_count, live_user_count, related_creator_count, video_play_count","example":"related_creator_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"related_creator_count:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品热推榜","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/rankings/new-arrivals":{"get":{"description":"查询近期上架并快速起量的 TikTok 新商品榜单。","operationId":"chuhaijiang-products-ranking-new-arrivals","parameters":[{"description":"商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"卖家类型：1=海外，2=本地，3=品牌，4=非品牌","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"上架日期范围起点，格式 YYYYMMDD","in":"query","name":"listed_from","required":false,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"上架日期范围终点，格式 YYYYMMDD","in":"query","name":"listed_to","required":false,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"商品状态选项 ID：1、2、3、4","in":"query","name":"product_status","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：gmv_3d, sold_count_3d, total_gmv, total_sold_count","example":"gmv_3d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_3d:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品新品榜","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/rankings/top-selling":{"get":{"description":"按统计周期查询 TikTok 商品销量榜，支持筛选、排序和分页。","operationId":"chuhaijiang-products-ranking-top-selling","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"卖家类型：1=海外，2=本地，3=品牌，4=非品牌","in":"query","name":"seller_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：gmv_growth_rate, interval_gmv, interval_sold_count, sold_count_growth_rate, total_gmv, total_sold_count","example":"interval_sold_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"interval_sold_count:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品销量榜","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/search":{"get":{"description":"搜索 TikTok 商品，支持关键词、类目、价格、销量等多维度过滤","operationId":"chuhaijiang-products-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"商品分类ID（数字），可从搜索结果的 l1_category 字段获取","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"卖家类型：1=海外非品牌, 2=本地, 3=品牌, 4=非品牌","example":"local","in":"query","name":"seller_type","required":false,"schema":{"type":"string"}},{"description":"最低价格（美元）","example":1,"in":"query","name":"min_price","required":false,"schema":{"type":"number"}},{"description":"最高价格（美元）","example":100,"in":"query","name":"max_price","required":false,"schema":{"type":"number"}},{"description":"最低评分（0-5）","example":4,"in":"query","name":"min_rating","required":false,"schema":{"type":"number"}},{"description":"最高评分（0-5）","example":5,"in":"query","name":"max_rating","required":false,"schema":{"type":"number"}},{"description":"7天最低销量","example":100,"in":"query","name":"min_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7天最高销量","example":10000,"in":"query","name":"max_sold_7d","required":false,"schema":{"type":"number"}},{"description":"30天最低销量","example":500,"in":"query","name":"min_sold_30d","required":false,"schema":{"type":"number"}},{"description":"30天最高销量","example":50000,"in":"query","name":"max_sold_30d","required":false,"schema":{"type":"number"}},{"description":"是否包邮","example":true,"in":"query","name":"free_shipping","required":false,"schema":{"type":"boolean"}},{"description":"排序，格式: field:asc|desc。支持: daily_sold, gmv_30d, gmv_7d, price, rating, sold_30d, sold_7d。默认: gmv_7d:desc","example":"gmv_7d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_7d:desc","enum":["daily_sold","gmv_30d","gmv_7d","price","rating","sold_30d","sold_7d"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"category_monthly_gmv":{"description":"类目月GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"category_opportunity":{"description":"类目机会指数","type":"number"},"category_seller_count":{"description":"类目店铺数","type":"integer"},"ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","type":"number"},"create_time":{"description":"创建时间(ms时间戳)","type":"integer"},"creator_sold_rate":{"description":"达人出单率(0-1)","type":"number"},"creator_total_play_count":{"description":"达人总播放量","type":"integer"},"cross_platform_amazon_est_monthly_sales_max":{"description":"Amazon预估月销量(上限)","type":"integer"},"cross_platform_amazon_est_monthly_sales_min":{"description":"Amazon预估月销量(下限)","type":"integer"},"cross_platform_amazon_product_count":{"description":"Amazon同款商品数","type":"integer"},"cross_platform_shopify_product_count":{"description":"Shopify同款商品数","type":"integer"},"cross_platform_shopify_site_count":{"description":"Shopify站点数","type":"integer"},"floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"id":{"description":"唯一标识","type":"string"},"l1_category":{"description":"一级类目","type":"string"},"original_ceiling_price":{"description":"原始最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"original_floor_price":{"description":"原始最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_daily_gmv":{"description":"日GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_daily_sold_count":{"description":"日销量","type":"integer"},"product_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_gmv_for_last_30_days":{"description":"近30日GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_gmv_for_last_3_days":{"description":"近3日GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_gmv_for_last_7_days":{"description":"近7日GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"product_name":{"description":"商品名称","type":"string"},"product_rating":{"description":"商品评分(0-5)","type":"number"},"product_sold_count":{"description":"总销量","type":"integer"},"product_sold_count_for_last_30_days":{"description":"近30日销量","type":"integer"},"product_sold_count_for_last_3_days":{"description":"近3日销量","type":"integer"},"product_sold_count_for_last_7_days":{"description":"近7日销量","type":"integer"},"region":{"description":"地区代码","type":"string"},"review_count":{"description":"评论数","type":"integer"},"seasonal_signal":{"description":"季节性信号","properties":{"month_range":{"description":"季节月份范围","type":"string"},"peak_month":{"description":"峰值月份","type":"string"},"peak_month_gmv":{"description":"峰值月份GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"total_gmv":{"description":"季节总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"total_sold":{"description":"季节总销量","type":"integer"}},"type":"object"},"seller_avatar":{"description":"店铺头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"type":"array"},"seller_id":{"description":"店铺ID","type":"string"},"shipping_fee":{"description":"运费","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"shop_name":{"description":"店铺名称","type":"string"},"shop_total_sold_count":{"description":"店铺总销量","type":"integer"},"signal_description":{"description":"信号描述","type":"string"},"signal_type":{"description":"信号类型","type":"string"},"sold_count_trend":{"description":"销量趋势(近7天)","items":{"properties":{"timestamp":{"description":"时间戳(ms)","type":"integer"},"value":{"description":"数值","type":"number"}},"type":"object"},"type":"array"},"spike_pct":{"description":"飙升百分比","type":"number"},"total_related_creator_count":{"description":"关联达人数","type":"integer"},"total_related_video_count":{"description":"关联视频数","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品搜索","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}":{"get":{"description":"获取 TikTok 商品详情，含关联视频、达人、评论","operationId":"chuhaijiang-products-detail","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: channel(销售渠道), core(核心指标)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","type":"number"},"create_time":{"description":"上架时间","type":"integer"},"floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"id":{"description":"唯一标识","type":"string"},"l1_category":{"description":"一级类目","type":"string"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"original_ceiling_price":{"description":"原始最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"original_floor_price":{"description":"原始最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"product_id":{"description":"商品ID","type":"string"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"product_name":{"description":"商品名称","type":"string"},"product_rating":{"description":"商品评分(0-5)","type":"number"},"product_sku_props":{"description":"SKU属性","items":{"properties":{"has_image":{"description":"是否有图片","type":"boolean"},"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名","type":"string"},"sale_prop_values":{"description":"属性值列表","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"product_skus":{"description":"SKU列表","items":{"properties":{"is_hot":{"description":"是否热销","type":"boolean"},"price":{"properties":{"discount":{"description":"折扣信息","type":"string"},"original_price":{"description":"原价","type":"string"},"original_price_value":{"description":"原价数值","type":"string"},"real_price":{"description":"实际价格","type":"number"},"unit_price_desc":{"description":"单价描述","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"属性值ID组合","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU属性","items":{"properties":{"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名(如Color)","type":"string"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"状态(1=在售)","type":"integer"},"stock":{"description":"库存","type":"integer"}},"type":"object"},"type":"array"},"product_specifications":{"description":"商品规格参数","items":{"properties":{"name":{"description":"规格名","type":"string"},"value":{"description":"规格值","type":"string"}},"type":"object"},"type":"array"},"region":{"description":"地区代码","type":"string"},"review_count":{"description":"评论数","type":"integer"},"seller_avatar":{"description":"店铺头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"type":"array"},"seller_creator_avatar":{"description":"达人头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"seller_creator_follow_count":{"description":"达人粉丝数","type":"string"},"seller_creator_nickname":{"description":"达人昵称","type":"string"},"seller_creator_role":{"description":"达人角色","type":"integer"},"seller_creator_user_id":{"description":"达人用户ID","type":"string"},"seller_creator_user_name":{"description":"达人用户名","type":"string"},"seller_id":{"description":"店铺ID","type":"string"},"shipping_fee":{"description":"运费","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"shop_main_category":{"description":"店铺主营类目","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"shop_rating":{"description":"店铺评分","type":"number"},"shop_total_gmv":{"description":"店铺总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"shop_total_sold_count":{"description":"店铺总销量","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品详情","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}/creators":{"get":{"description":"","operationId":"chuhaijiang-products-creators","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_author_avg_engagement_rate":{"description":"平均互动率","type":"number"},"tiktok_product_detail_author_avg_like_cnt":{"description":"作者平均点赞数","type":"number"},"tiktok_product_detail_author_avg_play_cnt":{"description":"作者平均播放量","type":"number"},"tiktok_product_detail_author_total_like_cnt":{"description":"作者总点赞数","type":"integer"},"tiktok_product_detail_author_total_play_cnt":{"description":"作者总播放量","type":"integer"},"tiktok_product_detail_by_live":{"description":"是否通过直播带货","type":"boolean"},"tiktok_product_detail_by_shop":{"description":"是否通过店铺售卖","type":"boolean"},"tiktok_product_detail_by_video":{"description":"是否通过视频带货","type":"boolean"},"tiktok_product_detail_category_label":{"description":"达人分类标签","type":"string"},"tiktok_product_detail_country_code":{"description":"国家代码","type":"string"},"tiktok_product_detail_creator_bio_email":{"description":"简介邮箱","type":"string"},"tiktok_product_detail_creator_facebook_url":{"description":"Facebook链接","type":"string"},"tiktok_product_detail_creator_ins_id":{"description":"Instagram账号","type":"string"},"tiktok_product_detail_creator_linkedin_url":{"description":"LinkedIn链接","type":"string"},"tiktok_product_detail_creator_related_total_live":{"description":"关联直播总数","type":"integer"},"tiktok_product_detail_creator_related_total_video":{"description":"关联视频总数","type":"string"},"tiktok_product_detail_creator_telegram_url":{"description":"Telegram链接","type":"string"},"tiktok_product_detail_creator_twitter_id":{"description":"Twitter/X账号","type":"string"},"tiktok_product_detail_creator_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_creator_video_7d_gmv":{"description":"近7天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_creator_whatsapp_url":{"description":"WhatsApp链接","type":"string"},"tiktok_product_detail_creator_youtube_channel_id":{"description":"YouTube频道ID","type":"string"},"tiktok_product_detail_follower_count":{"description":"粉丝数","type":"integer"},"tiktok_product_detail_live_30d_gmv":{"description":"近30天直播GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_live_7d_gmv":{"description":"近7天直播GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_nickname":{"description":"昵称","type":"string"},"tiktok_product_detail_product_id":{"description":"商品ID","type":"string"},"tiktok_product_detail_total_video_live_30d_gmv":{"description":"近30天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_total_video_live_7d_gmv":{"description":"近7天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_uid":{"description":"用户ID","type":"string"},"tiktok_product_detail_unique_id":{"description":"TikTok 用户名","type":"string"},"tiktok_product_detail_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_user_id":{"description":"用户ID","type":"string"},"tiktok_product_detail_video_total_like_count_to_follower_count_ratio":{"description":"视频总赞数/粉丝数比值","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品关联达人","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}/lives":{"get":{"description":"","operationId":"chuhaijiang-products-lives","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_country_code":{"description":"国家代码","type":"string"},"tiktok_product_detail_cover":{"description":"直播封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_end_time":{"description":"结束时间(ms时间戳)","type":"integer"},"tiktok_product_detail_gpm":{"description":"GPM(千次观看成交额)","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_live_total_sold_count":{"description":"直播总销量","type":"integer"},"tiktok_product_detail_max_user_count":{"description":"最高在线人数","type":"integer"},"tiktok_product_detail_most_product_category_label":{"description":"主要商品分类","type":"string"},"tiktok_product_detail_new_follower_count":{"description":"新增粉丝数","type":"integer"},"tiktok_product_detail_nickname":{"description":"昵称","type":"string"},"tiktok_product_detail_opm":{"description":"OPM(千次观看订单数)","type":"number"},"tiktok_product_detail_product_count":{"description":"商品数量","type":"integer"},"tiktok_product_detail_room_id":{"description":"直播间ID","type":"string"},"tiktok_product_detail_room_link":{"description":"直播间链接","type":"string"},"tiktok_product_detail_start_time":{"description":"开始时间(ms时间戳)","type":"integer"},"tiktok_product_detail_title":{"description":"直播标题","type":"string"},"tiktok_product_detail_total_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_total_user":{"description":"总观看人数","type":"integer"},"tiktok_product_detail_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_user_category_label":{"description":"用户分类标签","type":"string"},"tiktok_product_detail_user_id":{"description":"用户ID","type":"string"},"tiktok_product_detail_user_unique_id":{"description":"用户TikTok用户名","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品关联直播","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}/reviews":{"get":{"description":"","operationId":"chuhaijiang-products-reviews","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_review_content":{"description":"评论内容","type":"string"},"tiktok_product_detail_review_id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_review_images":{"description":"图片列表","type":"array"},"tiktok_product_detail_review_media":{"description":"媒体资源","properties":{"cover_url":{"description":"视频封面链接","type":"string"},"video_url":{"description":"视频链接","type":"string"}},"type":"object"},"tiktok_product_detail_review_product_id":{"description":"商品ID","type":"string"},"tiktok_product_detail_review_publish_time":{"description":"发布时间(ms时间戳)","type":"string"},"tiktok_product_detail_review_rating":{"description":"评分","type":"integer"},"tiktok_product_detail_review_sku_id":{"description":"SKU ID(商品规格标识)","type":"string"},"tiktok_product_detail_review_sku_image":{"description":"SKU图片","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_review_sku_specification":{"description":"SKU规格","type":"string"},"tiktok_product_detail_review_translated_review":{"description":"翻译后评论","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品评论","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}/similar":{"get":{"description":"","operationId":"chuhaijiang-products-similar","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_similar_l1_category":{"description":"一级类目","type":"string"},"tiktok_product_detail_similar_l2_category":{"description":"二级类目","type":"string"},"tiktok_product_detail_similar_l3_category":{"description":"三级类目","type":"string"},"tiktok_product_detail_similar_product_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_similar_product_id":{"description":"商品ID","type":"string"},"tiktok_product_detail_similar_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_similar_product_name":{"description":"商品名称","type":"string"},"tiktok_product_detail_similar_product_rating":{"description":"商品评分(0-5)","type":"number"},"tiktok_product_detail_similar_product_sold_count":{"description":"总销量","type":"integer"},"tiktok_product_detail_similar_region":{"description":"地区代码","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"相似商品","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/products/{id}/videos":{"get":{"description":"","operationId":"chuhaijiang-products-videos","parameters":[{"description":"商品ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_ad_source":{"description":"广告来源(1=有)","type":"integer"},"tiktok_product_detail_country_code":{"description":"国家代码","type":"string"},"tiktok_product_detail_cover_url":{"description":"封面图","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_is_ad":{"description":"是否广告投放","type":"boolean"},"tiktok_product_detail_is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"tiktok_product_detail_product_id":{"description":"商品ID","type":"string"},"tiktok_product_detail_share_url":{"description":"TikTok分享链接","type":"string"},"tiktok_product_detail_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_product_detail_user_id":{"description":"用户ID","type":"string"},"tiktok_product_detail_user_nickname":{"description":"用户昵称","type":"string"},"tiktok_product_detail_user_unique_id":{"description":"用户TikTok用户名","type":"string"},"tiktok_product_detail_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_video_30d_play_count":{"description":"近30天视频播放量","type":"integer"},"tiktok_product_detail_video_30d_sold_count":{"description":"近30天视频带货销量","type":"integer"},"tiktok_product_detail_video_desc":{"description":"视频描述","type":"string"},"tiktok_product_detail_video_duration":{"description":"视频时长(ms)","type":"integer"},"tiktok_product_detail_video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"tiktok_product_detail_video_id":{"description":"视频ID","type":"string"},"tiktok_product_detail_video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"tiktok_product_detail_video_like_count":{"description":"点赞数","type":"integer"},"tiktok_product_detail_video_play_count":{"description":"播放量","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品关联视频","tags":["数据查询/1.商品数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.products.read"}},"/open/v1/reports/{id}":{"get":{"description":"按报告 ID 返回报告详情（含所属 `session_id`）。免费接口。","operationId":"get-report","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"报告 ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"content":"Markdown 内容","created_at":"2026-05-20T10:00:00Z","id":"rpt-xxxx","session_id":"sess-xxxx","title":"报告标题","updated_at":"2026-05-20T10:01:00Z"},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"content":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"session_id":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"description":"FORBIDDEN — 报告存在但所在会话属于其他用户（owner 校验失败）"},"404":{"description":"REPORT_NOT_FOUND — 报告不存在"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"获取单个报告详情","tags":["小匠Agent/2.会话与报告"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sellers/rankings/most-promoted":{"get":{"description":"按统计周期查询达人、视频和直播集中推广的 TikTok 店铺榜单。","operationId":"chuhaijiang-sellers-ranking-most-promoted","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"店铺主营商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"店铺类型：1=海外，2=本地，3=品牌，4=非品牌","in":"query","name":"shop_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：product_count, related_creator_count, related_video_count, shop_creator_count, total_related_creator_count, video_creator_count","example":"related_creator_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"related_creator_count:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺热推榜","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/rankings/top-selling":{"get":{"description":"按统计周期查询销量领先的 TikTok 店铺榜单。","operationId":"chuhaijiang-sellers-ranking-top-selling","parameters":[{"description":"统计日期，格式 YYYYMMDD","example":"20260803","in":"query","name":"date","required":true,"schema":{"pattern":"^\\d{8}$","type":"string"}},{"description":"统计粒度：daily/0=日，weekly/1=周，monthly/2=月","example":"daily","in":"query","name":"granularity","required":true,"schema":{"enum":["daily","weekly","monthly","0","1","2"],"type":"string"}},{"description":"店铺主营商品品类 ID","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"店铺类型：1=海外，2=本地，3=品牌，4=非品牌","in":"query","name":"shop_type","required":false,"schema":{"enum":["1","2","3","4"],"type":"string"}},{"description":"排序，格式 field:asc|desc；字段：gmv_growth_rate, interval_gmv, interval_sold_count, product_count, sold_count_growth_rate, total_gmv, total_sold_count","example":"interval_sold_count:desc","in":"query","name":"sort","required":false,"schema":{"default":"interval_sold_count:desc","type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 20","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"description":"榜单结果；字段前缀已移除","items":{"additionalProperties":true,"properties":{"id":{"description":"榜单实体唯一标识","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺销量榜","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/search":{"get":{"description":"搜索 TikTok 店铺，支持类目、评分、销量等多维度过滤","operationId":"chuhaijiang-sellers-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"店铺主营分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"卖家类型：1=海外非品牌, 2=本地, 3=品牌, 4=非品牌","example":"local","in":"query","name":"seller_type","required":false,"schema":{"type":"string"}},{"description":"最低店铺评分","example":4,"in":"query","name":"min_rating","required":false,"schema":{"type":"number"}},{"description":"最高店铺评分","example":5,"in":"query","name":"max_rating","required":false,"schema":{"type":"number"}},{"description":"7天最低销量","example":100,"in":"query","name":"min_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7天最高销量","example":10000,"in":"query","name":"max_sold_7d","required":false,"schema":{"type":"number"}},{"description":"7天最低销售额（美元）","example":500,"in":"query","name":"min_gmv_7d","required":false,"schema":{"type":"number"}},{"description":"7天最高销售额（美元）","example":50000,"in":"query","name":"max_gmv_7d","required":false,"schema":{"type":"number"}},{"description":"排序，格式: field:asc|desc。支持: gmv_7d, product_count, rating, sold_7d, total_gmv, total_sold。默认: gmv_7d:desc","example":"gmv_7d:desc","in":"query","name":"sort","required":false,"schema":{"default":"gmv_7d:desc","enum":["gmv_7d","product_count","rating","sold_7d","total_gmv","total_sold"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"region":{"description":"地区代码","type":"string"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"type":"array"},"shop_gmv_for_last_7_days":{"description":"近7天GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"shop_main_category":{"description":"店铺主营类目","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"shop_product_count":{"description":"商品数量","type":"integer"},"shop_rating":{"description":"店铺评分","type":"number"},"shop_sold_count_for_last_7_days":{"description":"近7天销量","type":"integer"},"shop_total_gmv":{"description":"店铺总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"shop_total_sold_count":{"description":"店铺总销量","type":"integer"},"sold_count_trend":{"description":"销量趋势(近7天)","items":{"properties":{"timestamp":{"description":"时间戳(ms)","type":"integer"},"value":{"description":"数值","type":"number"}},"type":"object"},"type":"array"},"total_related_creator_count":{"description":"关联达人数","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺搜索","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/{id}":{"get":{"description":"获取 TikTok 店铺详情，含商品列表、关联达人","operationId":"chuhaijiang-sellers-detail","parameters":[{"description":"店铺ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: channel(销售渠道), core(核心指标)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"business_info":{"description":"商家信息","items":{"type":"string"},"type":"array"},"create_time":{"description":"上架时间","type":"integer"},"creator_avatar":{"description":"达人头像","type":"string"},"creator_follow_count":{"description":"达人粉丝数","type":"string"},"creator_nickname":{"description":"达人昵称","type":"string"},"creator_role":{"description":"达人角色","type":"integer"},"creator_user_id":{"description":"达人用户ID","type":"string"},"creator_user_name":{"description":"达人用户名","type":"string"},"id":{"description":"唯一标识","type":"string"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"region":{"description":"地区代码","type":"string"},"seller_avatar":{"description":"店铺头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"seller_id":{"description":"店铺ID","type":"string"},"shop_main_category":{"description":"店铺主营类目","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"shop_rating":{"description":"店铺评分","type":"number"},"shop_total_gmv":{"description":"店铺总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺详情","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/{id}/creators":{"get":{"description":"","operationId":"chuhaijiang-sellers-creators","parameters":[{"description":"店铺ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_seller_detail_creator_account_type":{"description":"账号类型","type":"integer"},"tiktok_seller_detail_creator_author_avg_engagement_rate":{"description":"平均互动率","type":"number"},"tiktok_seller_detail_creator_author_avg_like_cnt":{"description":"作者平均点赞数","type":"number"},"tiktok_seller_detail_creator_author_avg_play_cnt":{"description":"作者平均播放量","type":"number"},"tiktok_seller_detail_creator_author_total_play_cnt":{"description":"作者总播放量","type":"integer"},"tiktok_seller_detail_creator_bio_email":{"description":"简介邮箱","type":"string"},"tiktok_seller_detail_creator_by_live":{"description":"是否通过直播带货","type":"boolean"},"tiktok_seller_detail_creator_by_shop":{"description":"是否通过店铺售卖","type":"boolean"},"tiktok_seller_detail_creator_by_video":{"description":"是否通过视频带货","type":"boolean"},"tiktok_seller_detail_creator_category_label":{"description":"达人分类标签","type":"string"},"tiktok_seller_detail_creator_country_code":{"description":"国家代码","type":"string"},"tiktok_seller_detail_creator_facebook_url":{"description":"Facebook链接","type":"string"},"tiktok_seller_detail_creator_follower_count":{"description":"粉丝数","type":"integer"},"tiktok_seller_detail_creator_ins_id":{"description":"Instagram账号","type":"string"},"tiktok_seller_detail_creator_linkedin_url":{"description":"LinkedIn链接","type":"string"},"tiktok_seller_detail_creator_live_30d_gmv":{"description":"近30天直播GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_nickname":{"description":"昵称","type":"string"},"tiktok_seller_detail_creator_related_total_live":{"description":"关联直播总数","type":"integer"},"tiktok_seller_detail_creator_related_total_video":{"description":"关联视频总数","type":"integer"},"tiktok_seller_detail_creator_seller_id":{"description":"店铺ID","type":"string"},"tiktok_seller_detail_creator_telegram_url":{"description":"Telegram链接","type":"string"},"tiktok_seller_detail_creator_total_favorited":{"description":"总获赞数","type":"integer"},"tiktok_seller_detail_creator_total_video_live_30d_gmv":{"description":"近30天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_twitter_id":{"description":"Twitter/X账号","type":"string"},"tiktok_seller_detail_creator_unique_id":{"description":"TikTok 用户名","type":"string"},"tiktok_seller_detail_creator_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_seller_detail_creator_user_id":{"description":"用户ID","type":"string"},"tiktok_seller_detail_creator_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_video_7d_gmv":{"description":"近7天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_creator_video_count":{"description":"视频数","type":"integer"},"tiktok_seller_detail_creator_whatsapp_url":{"description":"WhatsApp链接","type":"string"},"tiktok_seller_detail_creator_youtube_channel_id":{"description":"YouTube频道ID","type":"string"},"tiktok_seller_detail_live_7d_gmv":{"description":"近7天直播GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_total_video_live_7d_gmv":{"description":"近7天视频+直播总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺关联达人","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/{id}/products":{"get":{"description":"","operationId":"chuhaijiang-sellers-products","parameters":[{"description":"店铺ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_seller_detail_product_detail_link":{"description":"商品详情链接","type":"string"},"tiktok_seller_detail_product_link":{"description":"商品链接","type":"string"},"tiktok_seller_product_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_product_commission_rate":{"description":"佣金率","type":"number"},"tiktok_seller_product_create_time":{"description":"上架时间","type":"integer"},"tiktok_seller_product_floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_product_l1_category":{"description":"一级类目","type":"string"},"tiktok_seller_product_l2_category":{"description":"二级类目","type":"string"},"tiktok_seller_product_l3_category":{"description":"三级类目","type":"string"},"tiktok_seller_product_product_gmv":{"description":"总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_product_product_gmv_for_last_7_days":{"description":"近7天商品GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_product_product_id":{"description":"商品ID","type":"string"},"tiktok_seller_product_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_name":{"description":"商品名称","type":"string"},"tiktok_seller_product_product_rating":{"description":"商品评分(0-5)","type":"number"},"tiktok_seller_product_product_sku_props":{"description":"SKU属性","items":{"properties":{"has_image":{"description":"是否有图片","type":"boolean"},"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名","type":"string"},"sale_prop_values":{"description":"属性值列表","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_skus":{"description":"SKU列表","items":{"properties":{"is_hot":{"description":"是否热销","type":"boolean"},"price":{"properties":{"discount":{"description":"折扣信息","type":"string"},"original_price":{"description":"原价","type":"string"},"original_price_value":{"description":"原价数值","type":"string"},"real_price":{"description":"实际价格","type":"number"},"unit_price_desc":{"description":"单价描述","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"属性值ID组合","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU属性","items":{"properties":{"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名(如Color)","type":"string"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"状态(1=在售)","type":"integer"},"stock":{"description":"库存","type":"integer"}},"type":"object"},"type":"array"},"tiktok_seller_product_product_sold_count":{"description":"总销量","type":"integer"},"tiktok_seller_product_product_sold_count_for_last_7_days":{"description":"近7天商品销量","type":"integer"},"tiktok_seller_product_product_status":{"description":"商品状态","type":"integer"},"tiktok_seller_product_region":{"description":"地区代码","type":"string"},"tiktok_seller_product_review_count":{"description":"评论数","type":"integer"},"tiktok_seller_product_total_related_creator_count":{"description":"关联达人总数","type":"integer"},"tiktok_seller_product_total_related_video_count":{"description":"关联视频总数","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺关联商品","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sellers/{id}/videos":{"get":{"description":"","operationId":"chuhaijiang-sellers-videos","parameters":[{"description":"店铺ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_seller_detail_cover_url":{"description":"封面图","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_seller_detail_follower_count":{"description":"粉丝数","type":"integer"},"tiktok_seller_detail_is_ad":{"description":"是否广告投放","type":"boolean"},"tiktok_seller_detail_is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"tiktok_seller_detail_share_url":{"description":"TikTok分享链接","type":"string"},"tiktok_seller_detail_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_seller_detail_user_id":{"description":"用户ID","type":"string"},"tiktok_seller_detail_user_nickname":{"description":"用户昵称","type":"string"},"tiktok_seller_detail_user_unique_id":{"description":"用户TikTok用户名","type":"string"},"tiktok_seller_detail_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_seller_detail_video_30d_play_count":{"description":"近30天视频播放量","type":"integer"},"tiktok_seller_detail_video_30d_sold_count":{"description":"近30天视频带货销量","type":"integer"},"tiktok_seller_detail_video_ad_source":{"description":"视频广告来源","type":"integer"},"tiktok_seller_detail_video_comment_count":{"description":"评论数","type":"integer"},"tiktok_seller_detail_video_country_code":{"description":"视频所在国家","type":"string"},"tiktok_seller_detail_video_desc":{"description":"视频描述","type":"string"},"tiktok_seller_detail_video_duration":{"description":"视频时长(ms)","type":"integer"},"tiktok_seller_detail_video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"tiktok_seller_detail_video_id":{"description":"视频ID","type":"string"},"tiktok_seller_detail_video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"tiktok_seller_detail_video_like_count":{"description":"点赞数","type":"integer"},"tiktok_seller_detail_video_play_count":{"description":"播放量","type":"integer"},"tiktok_seller_detail_video_seller_id":{"description":"店铺ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺关联视频","tags":["数据查询/4.店铺数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.sellers.read"}},"/open/v1/sessions":{"get":{"description":"返回当前用户(或代客目标用户)的会话列表，按需用 `q` 模糊搜索标题。`total` 为过滤后的总数，配合 `limit`/`offset` 翻页。免费接口。","operationId":"list-sessions","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"单页条数，默认 20，上限 100（上限由 nebula-claude 强制）","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"偏移，默认 0","in":"query","name":"offset","required":false,"schema":{"type":"integer"}},{"description":"标题模糊搜索（ILIKE）","in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"sessions":[{"created_at":"2026-05-20T10:00:00Z","id":"sess-xxxx","last_active_at":"2026-05-25T12:00:00Z","message_count":7,"status":"active","title":"会话标题"}],"total":42},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"sessions":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"last_active_at":{"format":"date-time","type":"string"},"message_count":{"type":"integer"},"status":{"description":"会话状态（默认 active）","enum":["active","archived"],"type":"string"},"title":{"type":"string"}},"type":"object"},"type":"array"},"total":{"type":"integer"}},"required":["sessions","total"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"列出当前用户的所有会话","tags":["小匠Agent/2.会话与报告"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sessions/{sid}":{"get":{"description":"返回指定会话的全部消息（含每条消息触发的异步任务）。`content` 保留原文，业务 XML 标签由客户端解析。","operationId":"get-session-messages","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"会话 ID","in":"path","name":"sid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"messages":[{"agent_id":"trenzer","attachments":null,"content":"string，可能含 \u003creport\u003e 等业务 XML 标签","created_at":"2026-05-20T10:00:00Z","id":"msg-xxxx","role":"assistant","tasks":[{"completed_at":"2026-05-20T10:00:05Z","created_at":"2026-05-20T10:00:01Z","display_name":"Generate Image","result_type":"image","status":"completed","task_id":"tk-xxxx","tool_name":"image_gen"}]}]},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"messages":{"items":{"properties":{"agent_id":{"type":"string"},"attachments":{"items":{"properties":{"media_type":{"type":"string"},"name":{"type":"string"},"os_bucket":{"type":"string"},"os_key":{"type":"string"}},"type":"object"},"nullable":true,"type":"array"},"content":{"description":"原文，可能含 \u003creport\u003e/\u003centity\u003e 等业务 XML 标签，解析责任在客户端","type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"role":{"enum":["user","assistant"],"type":"string"},"tasks":{"items":{"properties":{"completed_at":{"format":"date-time","type":"string"},"created_at":{"format":"date-time","type":"string"},"display_name":{"type":"string"},"result_type":{"description":"结果类型（默认 report，当前 3 种，未来可能扩展）","enum":["image","video","report"],"type":"string"},"status":{"description":"任务状态","enum":["pending","running","completed","failed","cancelled"],"type":"string"},"task_id":{"type":"string"},"tool_name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"required":["messages"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"description":"SESSION_NOT_FOUND — 会话不存在或不属于当前用户（合并语义，避免通过状态码探测会话是否存在）"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"获取某会话的消息列表","tags":["小匠Agent/2.会话与报告"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/sessions/{sid}/reports":{"get":{"description":"返回指定会话内生成的全部报告，按 `created_at` 倒序。免费接口。","operationId":"get-session-reports","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"会话 ID","in":"path","name":"sid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"reports":[{"content":"Markdown 内容","created_at":"2026-05-20T10:00:00Z","id":"rpt-xxxx","message_id":"msg-xxxx","title":"报告标题","updated_at":"2026-05-20T10:01:00Z"}]},"request_id":"req-xxxx"},"schema":{"properties":{"data":{"properties":{"reports":{"items":{"properties":{"content":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"message_id":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"}},"required":["reports"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"description":"SESSION_NOT_FOUND — 会话不存在或不属于当前用户（合并语义，避免通过状态码探测会话是否存在）"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"获取某会话的所有报告","tags":["小匠Agent/2.会话与报告"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/social/accounts/list":{"post":{"description":"查询社媒账号列表（含粉丝数、互动指标、带货数据等全量指标）。sort_by 支持按 followers / views / likes / comments / shares / engagement / gmv / orders 等指标排序，可用于生成任意指标的账号排行；支持按平台、状态、分组、关键词筛选。","operationId":"chuhaijiang-social-accounts-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"filter_unread":{"description":"按未读评论筛选。true = 仅返回有未读评论的账号，false = 仅返回无未读评论的账号，不传 = 不筛选","type":"boolean"},"group_id":{"description":"分组筛选。传数字 ID 筛选指定分组；传 \"ungrouped\" 筛选未分组账号；不传或传空字符串返回全部","type":"string"},"keyword":{"description":"搜索关键词，匹配用户名、显示名称、备注（模糊搜索）","type":"string"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"page_size":{"default":10,"description":"每页条数，默认 10","maximum":50,"type":"integer"},"platform_account_ids":{"description":"按账号 ID 精确筛选，传入账号 ID 列表","items":{"type":"integer"},"type":"array"},"platforms":{"description":"平台筛选（多选）。可选值：tiktok / tiktok-shop-pc / instagram / youtube / facebook","items":{"type":"string"},"type":"array"},"sort_by":{"default":"created_at","description":"排序字段。可选值：created_at（默认）/ display_name / followers / total_content / views / likes / comments / shares / favorites / engagement / avg_views / gmv / orders / last_synced","type":"string"},"sort_order":{"default":"desc","description":"排序方向。可选值：desc（默认，降序）/ asc（升序）","type":"string"},"statuses":{"description":"状态筛选（多选）。可选值：active / expired","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"items":{"properties":{"account_type":{"description":"账号类型：creator（创作者）/ business（商业号）","type":"string"},"avatar_url":{"description":"头像 URL","type":"string"},"avg_views_per_content":{"description":"平均每条内容播放量，无内容时不返回","type":"number"},"created_at":{"description":"绑定时间（Unix 时间戳，秒）","type":"integer"},"display_name":{"description":"账号显示名称","type":"string"},"engagement_rate":{"description":"互动率（%），计算方式：(likes + comments + shares + favorites) / views × 100","type":"number"},"followers":{"description":"粉丝数","type":"integer"},"gmv":{"description":"GMV 金额（仅 TikTok Shop 账号返回）","type":"number"},"gmv_currency":{"description":"GMV 货币单位（仅 TikTok Shop 账号返回）","type":"string"},"group_id":{"description":"所属分组 ID，null 表示未分组","type":"integer"},"group_name":{"description":"所属分组名称","type":"string"},"id":{"description":"账号 ID（系统内部标识）","type":"integer"},"image_count":{"description":"图片数量","type":"integer"},"items_sold":{"description":"售出件数（仅 TikTok Shop 账号返回）","type":"integer"},"orders":{"description":"订单数（仅 TikTok Shop 账号返回）","type":"integer"},"platform":{"description":"平台标识：tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"region":{"description":"账号所属区域（仅 TikTok Shop 账号返回，如 US / GB）","type":"string"},"remark":{"description":"用户自定义备注","type":"string"},"status":{"description":"账号状态：active（正常）/ expired（Token 过期）","type":"string"},"sync_updated_at":{"description":"数据最后同步时间（Unix 时间戳，秒）。null 表示尚未同步","type":"integer"},"token_expires_at":{"description":"OAuth Token 过期时间（Unix 时间戳，秒）","type":"integer"},"total_comments":{"description":"总评论数","type":"integer"},"total_content_count":{"description":"发布内容总数（视频 + 图片 + 轮播）","type":"integer"},"total_favorites":{"description":"总收藏数（仅 TikTok / Instagram 返回）","type":"integer"},"total_likes":{"description":"总点赞数","type":"integer"},"total_shares":{"description":"总分享数（YouTube 不返回此字段）","type":"integer"},"total_views":{"description":"总播放量","type":"integer"},"unread_comment_count":{"description":"未读评论数","type":"integer"},"username":{"description":"平台用户名","type":"string"},"video_count":{"description":"视频数量","type":"integer"}},"type":"object"},"type":"array"},"platform_counts":{"description":"各平台账号数量统计。固定返回 tiktok / tiktok-shop-pc / instagram / youtube / facebook 五项，数量为 0 也会返回","items":{"properties":{"count":{"description":"该平台的账号数量","type":"integer"},"platform":{"description":"平台标识","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"符合筛选条件的账号总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"社媒账号列表","tags":["社媒管理/1.账号管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/analytics/account-trend":{"post":{"description":"按账号返回指定时间范围内的每日指标序列和区间汇总，包含播放/点赞/评论/分享/收藏/互动率/粉丝/发帖/均播/GMV 等维度，支持排序分页。","operationId":"chuhaijiang-social-analytics-account-trend","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"截止时间（Unix 秒），建议跨度不超过 35 天","type":"integer"},"page":{"default":1,"description":"页码，默认 1","type":"integer"},"page_size":{"default":10,"description":"每页条数，默认 10，最大 20","maximum":20,"type":"integer"},"platform_account_ids":{"description":"按账号 ID 筛选","items":{"type":"integer"},"type":"array"},"platforms":{"description":"平台筛选。如 [\"tiktok\", \"instagram\"]","items":{"type":"string"},"type":"array"},"sort_by":{"default":"views","description":"排序指标。可选值：views（播放量，默认）/ likes（点赞）/ comments（评论）/ shares（分享）/ favorites（收藏）/ posts（发帖数）/ followers（粉丝变化）/ gmv（销售额）/ orders（订单数）","type":"string"},"sort_order":{"default":"desc","description":"排序方向。可选值：desc（降序，默认）/ asc（升序）","type":"string"},"start_time":{"description":"起始时间（Unix 秒）","type":"integer"}},"required":["start_time","end_time"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"账号趋势数据列表","items":{"properties":{"anchor_display_rate":{"description":"锚点展示率（仅 TikTok Shop，0-1 小数）","type":"number"},"avatar_url":{"description":"头像 URL","type":"string"},"avg_views_per_post":{"description":"均播 = total_views / total_posts","type":"integer"},"click_through_rate":{"description":"点击率（仅 TikTok Shop，0-1 小数）","type":"number"},"daily":{"description":"每日指标序列（从 data_start_date 开始）","items":{"properties":{"anchor_display_rate":{"description":"当天锚点展示率（仅 TikTok Shop）","type":"number"},"avg_views":{"description":"当天均播 = views/posts","type":"integer"},"click_through_rate":{"description":"当天点击率（仅 TikTok Shop）","type":"number"},"comments":{"description":"日增评论","type":"integer"},"date":{"description":"日期 YYYY-MM-DD","type":"string"},"engagement_rate":{"description":"当天互动率 (%) = (likes+comments+shares+favorites)/views*100","type":"number"},"favorites":{"description":"日增收藏","type":"integer"},"followers":{"description":"当天粉丝数（快照值，非增量）","type":"integer"},"gmv":{"description":"当天 GMV（仅 TikTok Shop）","type":"number"},"items_sold":{"description":"当天售出件数（仅 TikTok Shop）","type":"integer"},"likes":{"description":"日增点赞","type":"integer"},"orders":{"description":"当天订单数（仅 TikTok Shop）","type":"integer"},"posts":{"description":"当天发帖数","type":"integer"},"shares":{"description":"日增分享","type":"integer"},"views":{"description":"日增播放","type":"integer"}},"type":"object"},"type":"array"},"data_start_date":{"description":"首次有数据的日期 YYYY-MM-DD，图表从此日开始","type":"string"},"display_name":{"description":"显示名称","type":"string"},"engagement_rate":{"description":"综合互动率 (%) = (likes+comments+shares+favorites)/views*100","type":"number"},"followers":{"description":"区间末粉丝数（快照值）","type":"integer"},"followers_change":{"description":"区间粉丝变化（末日 - 首日）","type":"integer"},"gmv":{"description":"GMV 销售额（仅 TikTok Shop）","type":"number"},"gmv_currency":{"description":"GMV 币种（目前全部 USD）","type":"string"},"image_count":{"description":"图片数量","type":"integer"},"items_sold":{"description":"售出件数（仅 TikTok Shop）","type":"integer"},"orders":{"description":"订单数（仅 TikTok Shop）","type":"integer"},"platform":{"description":"平台（tiktok / tiktok-shop-pc / instagram）","type":"string"},"platform_account_id":{"description":"账号 ID","type":"integer"},"region":{"description":"地区（仅 shop 账号）","type":"string"},"sync_updated_at":{"description":"数据最后同步时间戳（Unix 秒）","type":"integer"},"total_comments":{"description":"区间评论增量","type":"integer"},"total_favorites":{"description":"区间收藏增量","type":"integer"},"total_likes":{"description":"区间点赞增量","type":"integer"},"total_posts":{"description":"区间发帖数","type":"integer"},"total_shares":{"description":"区间分享增量","type":"integer"},"total_views":{"description":"区间播放增量","type":"integer"},"username":{"description":"用户名","type":"string"},"video_count":{"description":"视频数量","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的账号总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"账号数据趋势","tags":["社媒管理/5.数据分析"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/analytics/overview":{"post":{"description":"查询统计周期内的社媒数据分析看板：核心 KPI 指标卡（播放/互动率/粉丝/销售额/订单/售出件数，含环比变化率）、平台维度拆分、账号维度拆分及 AI 周期摘要。环比基于上期（与当期等长的紧邻前一时间段）自动计算。\n\n【2026-07 变更说明】本接口数据源已升级为新版分析看板，响应结构全面更新：新增环比变化率、平台/账号维度拆分与 AI 摘要，原扁平概览结构不再返回，请按最新响应字段说明接入。","operationId":"chuhaijiang-social-analytics-overview","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"统计截止时间（Unix 秒）","type":"integer"},"platform":{"default":"all","description":"平台筛选。可选值：all（全部平台，默认，此时返回 platforms 平台拆分）/ tiktok / tiktok-shop-pc（TikTok Shop 店铺）/ instagram / youtube","type":"string"},"start_time":{"description":"统计起始时间（Unix 秒）。与 end_time 构成统计周期（当期），环比自动对比与当期等长的紧邻前一周期","type":"integer"}},"required":["start_time","end_time"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"accounts":{"description":"账号维度拆分。platform=all 时仅含店铺账号（销售额/订单拆分）；platform=具体平台时含该平台全部账号（点击展开查看详细字段）","items":{"properties":{"avatar_url":{"description":"账号头像 URL（临时签名链接，有效期有限，请勿持久化保存）","type":"string"},"display_name":{"description":"账号展示名","type":"string"},"engagement_detail":{"description":"点赞/评论/分享增量拆分（点击展开查看详细字段）","properties":{"comments":{"description":"周期内评论增量","type":"integer"},"likes":{"description":"周期内点赞增量","type":"integer"},"shares":{"description":"周期内分享增量","type":"integer"}},"type":"object"},"engagement_rate":{"description":"周期内互动率百分比","type":"number"},"engagement_rate_change":{"description":"互动率环比变化率（比率）","type":"number"},"follower_growth":{"description":"周期内粉丝净增（新接入账号可能不返回）","type":"integer"},"followers":{"description":"当前粉丝总数","type":"integer"},"gmv":{"description":"周期内销售额（仅店铺账号返回）","type":"number"},"gmv_currency":{"description":"币种（仅店铺账号返回）","type":"string"},"platform":{"description":"账号所属平台","type":"string"},"platform_account_id":{"description":"账号 ID，与「社媒账号列表」的 id 一致","type":"integer"},"username":{"description":"平台用户名（如 @kitchen_tips）","type":"string"},"view_share":{"description":"该账号播放量占全部账号的比例（0.66 表示 66%）","type":"number"},"views":{"description":"周期内播放增量","type":"integer"}},"type":"object"},"type":"array"},"brief":{"description":"AI 周期摘要，基于规则模板生成，语言跟随请求 locale（点击展开查看详细字段）","properties":{"main":{"description":"核心表现摘要，1-3 句归因描述（如：播放量上涨 23% 至 95.1K，主要由 TikTok 贡献（占 61%））","type":"string"},"warning":{"description":"行动提醒（如某平台数据下滑及原因提示），无异常时不返回","type":"string"}},"type":"object"},"metrics":{"description":"KPI 指标卡数组，每项对应一个核心指标（点击展开查看详细字段）","items":{"properties":{"change_rate":{"description":"环比变化率（比率，0.23 表示 +23%）。上期无数据时不返回","type":"number"},"currency":{"description":"币种（仅 gmv / orders / items_sold 指标返回，如 USD）","type":"string"},"engagement_detail":{"description":"互动明细拆分，仅 engagement_rate 指标返回（点击展开查看详细字段）","properties":{"comments":{"description":"周期内评论增量","type":"integer"},"likes":{"description":"周期内点赞增量","type":"integer"},"shares":{"description":"周期内分享增量","type":"integer"}},"type":"object"},"metric":{"description":"指标名。可能值：views（播放）/ engagement_rate（互动率）/ followers（粉丝）/ gmv（销售额）/ orders（订单数）/ items_sold（售出件数）","type":"string"},"secondary_label":{"description":"副值标签，说明 secondary_value 的含义","type":"string"},"secondary_value":{"description":"副值数值，与 secondary_label 配套","type":"number"},"value":{"description":"指标主值。engagement_rate 为百分比数值（4.2 表示 4.2%），其余为原始数值","type":"number"}},"type":"object"},"type":"array"},"period":{"description":"统计周期信息。环比数据基于上期（与当期等长的紧邻前一时间段）计算（点击展开查看详细字段）","properties":{"end_date":{"description":"当期结束日期，格式 YYYY-MM-DD","type":"string"},"previous_end_date":{"description":"上期结束日期，格式 YYYY-MM-DD","type":"string"},"previous_start_date":{"description":"上期起始日期，格式 YYYY-MM-DD","type":"string"},"start_date":{"description":"当期起始日期，格式 YYYY-MM-DD","type":"string"}},"type":"object"},"platforms":{"description":"平台维度拆分，仅 platform=all 时返回（点击展开查看详细字段）","items":{"properties":{"account_count":{"description":"该平台下的账号数","type":"integer"},"engagement_detail":{"description":"点赞/评论/分享增量拆分（店铺类账号不返回）（点击展开查看详细字段）","properties":{"comments":{"description":"周期内评论增量","type":"integer"},"likes":{"description":"周期内点赞增量","type":"integer"},"shares":{"description":"周期内分享增量","type":"integer"}},"type":"object"},"engagement_rate":{"description":"周期内互动率百分比（店铺类账号不返回）","type":"number"},"engagement_rate_change":{"description":"互动率环比变化率（比率）","type":"number"},"followers":{"description":"该平台粉丝总量（店铺类账号不返回）","type":"integer"},"gmv":{"description":"周期内销售额（仅 tiktok-shop-pc 返回）","type":"number"},"gmv_currency":{"description":"销售额币种（仅 tiktok-shop-pc 返回）","type":"string"},"platform":{"description":"平台标识：tiktok / tiktok-shop-pc / instagram / youtube","type":"string"},"views":{"description":"周期内播放增量（店铺类账号不返回）","type":"integer"}},"type":"object"},"type":"array"},"posts_count":{"description":"当期发帖数","type":"integer"},"posts_count_prev":{"description":"上期发帖数，与 posts_count 相减可得发帖数变化","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"数据分析概览","tags":["社媒管理/5.数据分析"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/analytics/top-products":{"post":{"description":"按销售指标获取Top商品排行","operationId":"chuhaijiang-social-analytics-top-products","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_types":{"description":"账号类型筛选。可选值：creator / business","items":{"type":"string"},"type":"array"},"end_date":{"description":"截止日期（YYYY-MM-DD）","type":"string"},"limit":{"default":10,"description":"返回数量，默认 10，最大 50","maximum":50,"type":"integer"},"metric":{"description":"排序指标。可选值：gmv（GMV 金额）/ orders（订单数）/ video_count（关联视频数）","type":"string"},"platform_account_ids":{"description":"按账号 ID 筛选","items":{"type":"integer"},"type":"array"},"start_date":{"description":"起始日期（YYYY-MM-DD），不传默认近 7 天","type":"string"}},"required":["metric"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"products":{"description":"商品排行榜，按指标值降序排列","items":{"properties":{"image_url":{"description":"商品主图 URL","type":"string"},"platform_product_id":{"description":"平台侧商品 ID","type":"string"},"price_amount":{"description":"商品价格","type":"number"},"price_currency":{"description":"价格货币单位","type":"string"},"product_id":{"description":"商品 ID（系统内部标识）","type":"integer"},"title":{"description":"商品名称","type":"string"},"total_gmv":{"description":"统计期间总 GMV","type":"number"},"total_items_sold":{"description":"统计期间总售出件数","type":"integer"},"total_orders":{"description":"统计期间总订单数","type":"integer"},"video_count":{"description":"关联视频数","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"商品排行榜","tags":["社媒管理/5.数据分析"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/analytics/top-videos":{"post":{"description":"按指标获取Top视频排行","operationId":"chuhaijiang-social-analytics-top-videos","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_types":{"description":"账号类型筛选。可选值：creator / business","items":{"type":"string"},"type":"array"},"end_date":{"description":"截止日期（YYYY-MM-DD）","type":"string"},"limit":{"default":10,"description":"返回数量，默认 10，最大 50","maximum":50,"type":"integer"},"metric":{"description":"排序指标。可选值：views（播放量）/ likes（点赞）/ comments（评论）/ shares（分享）/ gmv（销售额）","type":"string"},"platform_account_ids":{"description":"按账号 ID 筛选","items":{"type":"integer"},"type":"array"},"platforms":{"description":"平台筛选。如 [\"tiktok\", \"instagram\"]","items":{"type":"string"},"type":"array"},"start_date":{"description":"起始日期（YYYY-MM-DD），不传默认近 7 天","type":"string"}},"required":["metric"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"videos":{"description":"视频排行榜，按指标值降序排列","items":{"properties":{"account_avatar_url":{"description":"账号头像 URL","type":"string"},"account_display_name":{"description":"账号显示名称","type":"string"},"anchor_display_rate":{"description":"商品锚点展示率（%，仅带货视频返回）","type":"number"},"click_through_rate":{"description":"点击率（%，仅带货视频返回）","type":"number"},"comment_count":{"description":"评论数","type":"integer"},"cover_url":{"description":"封面图 URL","type":"string"},"gmv_amount":{"description":"GMV 金额（仅带货视频返回）","type":"number"},"gmv_currency":{"description":"GMV 货币单位","type":"string"},"item_sold_count":{"description":"售出件数（仅带货视频返回）","type":"integer"},"like_count":{"description":"点赞数","type":"integer"},"metric_growth":{"description":"排序指标在统计期间内的增长量","type":"integer"},"order_count":{"description":"订单数（仅带货视频返回）","type":"integer"},"platform":{"description":"平台标识","type":"string"},"platform_account_id":{"description":"所属账号 ID","type":"integer"},"platform_url":{"description":"视频在平台上的 URL","type":"string"},"platform_video_id":{"description":"平台侧视频 ID","type":"string"},"product_id":{"description":"关联商品 ID（仅带货视频返回）","type":"string"},"product_image_url":{"description":"关联商品主图 URL（仅带货视频返回）","type":"string"},"product_title":{"description":"关联商品名称（仅带货视频返回）","type":"string"},"published_at":{"description":"发布时间（Unix 时间戳，秒）","type":"integer"},"region":{"description":"账号区域（仅 TikTok Shop 返回）","type":"string"},"share_count":{"description":"分享数","type":"integer"},"video_title":{"description":"视频标题","type":"string"},"view_count":{"description":"播放量","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频排行榜","tags":["社媒管理/5.数据分析"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/comments/create":{"post":{"description":"以账号身份在视频下发表新评论","operationId":"chuhaijiang-social-comments-create","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"平台账号ID","type":"integer"},"platform_video_id":{"description":"平台视频ID","type":"string"},"text":{"description":"评论内容","type":"string"}},"required":["platform_account_id","platform_video_id","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"author":{"properties":{"display_name":{"description":"评论者显示名称","type":"string"},"username":{"description":"评论者用户名","type":"string"}},"type":"object"},"like_count":{"description":"点赞数","type":"integer"},"platform":{"description":"平台标识","type":"string"},"platform_comment_id":{"description":"平台侧评论 ID","type":"string"},"platform_video_id":{"description":"所属视频的平台 ID","type":"string"},"published_at":{"description":"发布时间（Unix 时间戳，秒）","type":"integer"},"reply_count":{"description":"回复数","type":"integer"},"text":{"description":"评论内容","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"发表评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/comments/delete":{"post":{"description":"在平台上删除评论并更新本地状态。\n\n注意：受 TikTok API 限制，仅支持删除**自己账号发布**的评论；他人在你视频下发布的评论无法删除，请使用「隐藏评论」接口（POST /open/v1/social/comments/hide）将其对其他用户隐藏。","operationId":"chuhaijiang-social-comments-delete","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"平台账号ID","type":"integer"},"platform_comment_id":{"description":"评论ID","type":"string"},"platform_video_id":{"description":"平台视频ID","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"is_deleted":{"description":"是否已删除","type":"boolean"},"platform":{"description":"平台标识","type":"string"},"platform_comment_id":{"description":"平台侧评论 ID","type":"string"},"text":{"description":"评论内容","type":"string"}},"type":"object"},"success":{"description":"操作是否成功","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"删除评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/comments/hide":{"post":{"description":"隐藏或取消隐藏**他人**在你视频下发布的评论。隐藏后评论对其他用户不可见（状态变为 HIDDEN），可随时取消隐藏恢复。\n\n使用场景区分：他人发布的不当评论 → 用本接口隐藏；自己账号发布的评论 → 用「删除评论」接口删除（TikTok API 的删除仅支持删自己发的评论）。","operationId":"chuhaijiang-social-comments-hide","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"hidden":{"description":"true=隐藏评论（他人不可见），false=取消隐藏（恢复可见）","type":"boolean"},"platform_account_id":{"description":"平台账号 ID（视频作者账号），来自「社媒账号列表」返回的 id 字段","type":"integer"},"platform_comment_id":{"description":"要隐藏的评论 ID，来自「评论列表」或「回复列表」返回的 platform_comment_id 字段","type":"string"}},"required":["platform_account_id","platform_comment_id","hidden"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"hidden":{"description":"操作后评论的当前隐藏状态：true=已隐藏，false=可见","type":"boolean"},"success":{"description":"操作是否成功","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"隐藏评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/comments/like":{"post":{"description":"在平台上点赞或取消点赞评论","operationId":"chuhaijiang-social-comments-like","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"action":{"description":"操作：like/unlike","type":"string"},"platform_account_id":{"description":"平台账号ID","type":"integer"},"platform_comment_id":{"description":"评论ID","type":"string"},"platform_video_id":{"description":"平台视频ID","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id","action"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"comment":{"properties":{"is_liked":{"description":"当前点赞状态（操作后）","type":"boolean"},"like_count":{"description":"最新点赞数","type":"integer"},"platform":{"description":"平台标识","type":"string"},"platform_comment_id":{"description":"平台侧评论 ID","type":"string"},"text":{"description":"评论内容","type":"string"}},"type":"object"},"success":{"description":"操作是否成功","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"点赞评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/comments/managed":{"post":{"description":"查询本地已同步的**一级评论**列表（视频下的顶层评论），支持按账号/平台/视频筛选、关键词搜索、已读状态、隐藏状态等多维过滤。首次使用前需先调用「同步评论」接口拉取平台评论。\n\n与「回复列表」的区别：本接口返回视频下的一级评论；某条评论下的子回复请传该评论的 platform_comment_id 调用「回复列表」（POST /open/v1/social/comments/managed/replies）分页获取。","operationId":"chuhaijiang-social-comments-managed-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"engaged":{"description":"品牌互动筛选。true = 仅已回复过的评论（is_owner_replied=true）","type":"boolean"},"include_replies":{"description":"是否在每条评论下内联返回回复","type":"boolean"},"is_deleted":{"description":"删除状态筛选。true = 仅已删除评论，false = 仅未删除（默认）","type":"boolean"},"is_hidden":{"description":"隐藏状态筛选。true = 仅隐藏评论，false = 仅可见评论（默认）","type":"boolean"},"is_read":{"description":"已读状态筛选。true = 仅已读，false = 仅未读，不传 = 全部","type":"boolean"},"keyword":{"description":"搜索关键词，匹配评论内容","type":"string"},"limit":{"default":20,"description":"每页条数，默认 20，最大 100","maximum":100,"type":"integer"},"max_replies":{"description":"每条评论最多返回的回复数（仅 include_replies=true 时生效）","type":"integer"},"owner_replied":{"description":"是否已回复筛选。true = 已回复，false = 未回复。与 engaged 类似但语义更直接","type":"boolean"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"platform_account_ids":{"description":"按账号 ID 筛选","items":{"type":"integer"},"type":"array"},"platform_video_id":{"description":"平台侧视频 ID，筛选某个视频下的评论","type":"string"},"platforms":{"description":"平台筛选（多选）。可选值：tiktok / instagram / youtube / facebook","items":{"type":"string"},"type":"array"},"published_after":{"description":"评论发布时间起始（Unix 时间戳，秒）","type":"integer"},"published_before":{"description":"评论发布时间截止（Unix 时间戳，秒）","type":"integer"},"sort_by":{"description":"排序字段。可选值：published_at（发布时间，默认）/ like_count（点赞数）","type":"string"},"sort_order":{"description":"排序方向。可选值：desc（降序，默认）/ asc（升序）","type":"string"},"view_mode":{"description":"查看模式。可选值：priority（跨视频聚合，按 AI 优先级排序）。不传 = 普通列表","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"comments":{"items":{"properties":{"ai_context_hint":{"description":"AI 业务上下文提示（仅 opportunity 评论返回）","type":"string"},"ai_intent":{"description":"AI 意图分类：purchase_intent / negative_sentiment / high_value_user / collab_partnership / general / new_comment","type":"string"},"ai_priority":{"description":"AI 优先级：opportunity（商业机会）/ routine（常规）","type":"string"},"ai_priority_score":{"description":"AI 优先级评分（0.0-1.0）","type":"number"},"author":{"properties":{"avatar_url":{"description":"评论者头像 URL","type":"string"},"display_name":{"description":"评论者显示名称","type":"string"},"username":{"description":"评论者用户名","type":"string"}},"type":"object"},"id":{"description":"评论记录 ID（系统内部标识）","type":"integer"},"is_deleted":{"description":"是否已被删除","type":"boolean"},"is_hidden":{"description":"是否已隐藏","type":"boolean"},"is_liked":{"description":"你是否已点赞此评论","type":"boolean"},"is_owner_replied":{"description":"是否已回复此评论","type":"boolean"},"is_read":{"description":"是否已读","type":"boolean"},"is_self_comment":{"description":"是否是自己发的评论","type":"boolean"},"like_count":{"description":"评论点赞数","type":"integer"},"platform":{"description":"来源平台：tiktok / instagram / youtube","type":"string"},"platform_account_id":{"description":"所属账号 ID","type":"integer"},"platform_comment_id":{"description":"平台侧评论 ID","type":"string"},"platform_video_id":{"description":"所属视频的平台 ID","type":"string"},"published_at":{"description":"评论发布时间（Unix 时间戳，秒）","type":"integer"},"reply_count":{"description":"回复数","type":"integer"},"text":{"description":"评论内容","type":"string"}},"type":"object"},"type":"array"},"limit":{"description":"每页条数","type":"integer"},"page":{"description":"当前页码","type":"integer"},"total_count":{"description":"符合条件的评论总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"评论列表","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/comments/managed/replies":{"post":{"description":"查询指定评论下的**子回复**列表（需传父评论的 platform_comment_id），数据来源于「同步评论」操作，使用偏移量分页。\n\n与「评论列表」的区别：「评论列表」返回视频下的一级评论；本接口返回其中某一条评论下的回复。典型用法：先用「评论列表」拿到一级评论，对 reply_count \u003e 0 的评论再调本接口展开回复。","operationId":"chuhaijiang-social-comments-managed-replies","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"is_deleted":{"description":"删除状态筛选。true = 仅已删除回复，false = 仅未删除","type":"boolean"},"is_hidden":{"description":"隐藏状态筛选。true = 仅隐藏回复，false = 仅可见回复","type":"boolean"},"limit":{"default":20,"description":"每页条数，默认 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"platform_account_id":{"description":"账号 ID","type":"integer"},"platform_comment_id":{"description":"父评论的平台侧 ID","type":"string"}},"required":["platform_account_id","platform_comment_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"每页条数","type":"integer"},"page":{"description":"当前页码","type":"integer"},"replies":{"items":{"properties":{"author":{"properties":{"avatar_url":{"description":"回复者头像 URL","type":"string"},"display_name":{"description":"回复者显示名称","type":"string"},"username":{"description":"回复者用户名","type":"string"}},"type":"object"},"id":{"description":"回复记录 ID（系统内部标识）","type":"integer"},"is_liked":{"description":"你是否已点赞此回复","type":"boolean"},"is_read":{"description":"是否已读","type":"boolean"},"is_self_comment":{"description":"是否是自己发的回复","type":"boolean"},"like_count":{"description":"点赞数","type":"integer"},"platform_comment_id":{"description":"回复的平台侧 ID","type":"string"},"published_at":{"description":"发布时间（Unix 时间戳，秒）","type":"integer"},"text":{"description":"回复内容","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"回复总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"回复列表","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/comments/reply":{"post":{"description":"以账号身份回复评论","operationId":"chuhaijiang-social-comments-reply","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"平台账号ID","type":"integer"},"platform_comment_id":{"description":"评论ID","type":"string"},"platform_video_id":{"description":"平台视频ID","type":"string"},"text":{"description":"回复内容","type":"string"}},"required":["platform_account_id","platform_video_id","platform_comment_id","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"reply":{"properties":{"author":{"properties":{"display_name":{"description":"回复者显示名称","type":"string"},"username":{"description":"回复者用户名","type":"string"}},"type":"object"},"like_count":{"description":"点赞数","type":"integer"},"platform":{"description":"平台标识","type":"string"},"platform_comment_id":{"description":"回复的平台侧 ID","type":"string"},"published_at":{"description":"发布时间（Unix 时间戳，秒）","type":"integer"},"text":{"description":"回复内容","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"回复评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/comments/sync":{"post":{"description":"触发从平台拉取并同步评论到本地。这是一个异步操作，返回本次同步的统计数据。同步完成后可通过「评论列表」接口查看结果。","operationId":"chuhaijiang-social-comments-sync","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"账号 ID。系统将拉取该账号下所有视频的最新评论","type":"integer"},"platform_video_id":{"description":"可选。指定视频的平台 ID，仅同步该视频的评论。不传则同步该账号下所有视频","type":"string"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"comments_synced":{"description":"本次新同步的评论数量","type":"integer"},"errors":{"description":"同步过程中发生的错误数量","type":"integer"},"replies_synced":{"description":"本次新同步的回复数量","type":"integer"},"videos_processed":{"description":"本次处理的视频数量","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"同步评论","tags":["社媒管理/4.评论互动"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/hashtag/suggestions":{"post":{"description":"根据关键词获取TikTok热门hashtag推荐","operationId":"chuhaijiang-social-hashtag-suggestions","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"搜索关键词（单词）","type":"string"},"language":{"description":"语言代码，默认en","type":"string"}},"required":["keyword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"from_cache":{"description":"结果是否来自缓存。true = 缓存命中，false = 实时从 TikTok API 获取","type":"boolean"},"suggestions":{"description":"推荐的 Hashtag 列表，按热度降序排列","items":{"properties":{"name":{"description":"Hashtag 名称（不含 # 号）","type":"string"},"view_count":{"description":"该 Hashtag 的总观看量","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"Hashtag推荐","tags":["社媒管理/6.创作工具"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/channels/list":{"post":{"description":"查询已绑定的社媒私信渠道（账号通道）列表，覆盖 WhatsApp/WhatsApp Business/LINE/TikTok/Facebook/Instagram，含未读数、同步状态、平台健康信息","operationId":"chuhaijiang-social-im-channels-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_ids":{"description":"按渠道 ID 精确筛选（可多个）","example":["550e8400-e29b-41d4-a716-446655440000"],"items":{"type":"string"},"type":"array"},"filter_unread":{"description":"true 时仅返回存在未读消息的渠道","example":true,"type":"boolean"},"limit":{"description":"每页返回条数（必填），范围 1-50","example":20,"type":"integer"},"name":{"description":"模糊搜索关键词，匹配渠道名称、渠道备注；WhatsApp 渠道还匹配绑定手机号（自动忽略 + 号和空格）","example":"客服","type":"string"},"offset":{"description":"分页偏移量，从 0 开始，默认 0；第 2 页传 limit×1，第 3 页传 limit×2，以此类推","example":0,"type":"integer"},"order":{"description":"排序方向：DESC（降序，默认）| ASC（升序）","enum":["DESC","ASC"],"example":"DESC","type":"string"},"order_by":{"description":"排序字段：created_at（绑定时间，默认）| updated_at（更新时间）| name（名称）","enum":["created_at","updated_at","name"],"example":"created_at","type":"string"},"platform_connection_ids":{"description":"按平台侧账号标识筛选（可多个），如 WhatsApp 手机号","example":["5216642344918"],"items":{"type":"string"},"type":"array"},"platform_type":{"description":"按平台筛选，不传返回全部平台。渠道即绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话。","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"status":{"description":"按渠道状态筛选（可多选）：active（正常）| pending_approval（待审核）| disconnected（已断开）| suspended（已暂停）| deleted（已删除）；不传默认只返回 active 渠道","example":["active"],"items":{"enum":["active","pending_approval","disconnected","suspended","deleted"],"type":"string"},"type":"array"}},"required":["limit","offset"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"渠道列表。渠道即绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话。","items":{"properties":{"ai_automation_level":{"description":"AI 自动回复等级：off（关闭）| autopilot（全自动回复）","enum":["off","autopilot"],"example":"off","type":"string"},"avatar":{"description":"渠道头像 URL（签名链接，30 天有效期）","example":"https://cdn.example.com/avatar/ch.jpg","type":"string"},"channel_id":{"description":"渠道 ID（UUID 格式），查会话列表等后续接口以此为入参","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"created_at":{"description":"绑定时间（Unix 秒）","example":1780000000,"type":"integer"},"name":{"description":"渠道名称（社媒账号名或绑定手机号）；名称为空时返回平台侧账号标识","example":"官方客服 WhatsApp","type":"string"},"platform":{"description":"所属社媒平台：whatsapp（WhatsApp 个人版）| whatsapp_business（WhatsApp Business）| line | tiktok | facebook（Messenger）| instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"platform_connection_id":{"description":"平台侧账号标识：WhatsApp 为手机号、WhatsApp Business 为 phone_number_id、Facebook 为主页 ID、Instagram 为 IG 账号 ID","example":"5216642344918","type":"string"},"remark":{"description":"渠道备注","example":"泰国市场主号","type":"string"},"status":{"description":"渠道状态：active（正常）| pending_approval（待审核）| disconnected（已断开，需重新授权）| suspended（已暂停）| deleted（已删除）| pending_pin（两步验证待输入）| registration_failed（号码注册失败，可重试）","enum":["active","pending_approval","disconnected","suspended","deleted","pending_pin","registration_failed"],"example":"active","type":"string"},"sync_status":{"description":"历史消息同步状态：pending（待同步）| syncing（同步中）| success（已完成）| failed（失败）；从未同步时不返回","enum":["pending","syncing","success","failed"],"example":"success","type":"string"},"unread_count":{"description":"该渠道未读消息总数","example":12,"type":"integer"},"updated_at":{"description":"最近更新时间（Unix 秒）","example":1783670000,"type":"integer"},"user_id":{"description":"渠道归属用户 ID","example":"6a7ef569","type":"string"},"wa_account_review_status":{"description":"WhatsApp Business 专用：账号审核状态","enum":["APPROVED","PENDING","REJECTED","VIOLATION"],"example":"APPROVED","type":"string"},"wa_health_snapshot":{"description":"WhatsApp Business 专用：健康诊断快照（点击展开查看详细字段）","properties":{"checked_at":{"description":"最近检查时间（Unix 秒）","example":1783670000,"type":"integer"},"issues":{"description":"问题列表，正常时为空","items":{"properties":{"entity_type":{"description":"问题实体类型","enum":["PHONE_NUMBER","WABA","BUSINESS","APP","MESSAGE_TEMPLATE"],"example":"PHONE_NUMBER","type":"string"},"error_code":{"description":"Meta 错误代码（仅 BLOCKED 时提供）","example":141000,"type":"integer"},"message":{"description":"问题描述","example":"Messaging limit reached","type":"string"},"severity":{"description":"严重程度","enum":["LIMITED","BLOCKED"],"example":"LIMITED","type":"string"},"solution":{"description":"解决建议（仅 BLOCKED 时提供）","example":"Verify your business","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"整体健康状态：AVAILABLE（正常）| LIMITED（受限）| BLOCKED（被封锁）","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE","type":"string"}},"type":"object"},"wa_messaging_limit":{"description":"WhatsApp Business 专用：24 小时内可主动触达的用户数量级","enum":["TIER_50","TIER_250","TIER_1K","TIER_10K","TIER_100K","TIER_UNLIMITED"],"example":"TIER_1K","type":"string"},"wa_phone_status":{"description":"WhatsApp Business 专用：号码连接状态","enum":["CONNECTED","OFFLINE","FLAGGED","RATE_LIMITED","BANNED","RESTRICTED"],"example":"CONNECTED","type":"string"},"wa_quality_rating":{"description":"WhatsApp Business 专用：号码质量评级（GREEN 最佳）","enum":["GREEN","YELLOW","RED"],"example":"GREEN","type":"string"},"wa_verified_name":{"description":"WhatsApp Business 专用：Meta 认证的商家名称","example":"Example Store","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的渠道总数（用于分页）","example":3,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信渠道列表","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/channels/unread-count":{"post":{"description":"汇总各私信渠道的未读消息数，用于展示红点/角标","operationId":"chuhaijiang-social-im-channels-unread-count","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_ids":{"description":"渠道 ID 列表，不传则统计当前账号下全部正常（active）渠道；未读数为 0 的渠道也会返回。渠道 ID 通过「私信渠道列表」接口（社媒管理/8.私信管理 分类下）获取","example":["550e8400-e29b-41d4-a716-446655440000"],"items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"各渠道未读数列表","items":{"properties":{"channel_id":{"description":"渠道 ID","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"platform":{"description":"所属社媒平台：whatsapp（WhatsApp 个人版）| whatsapp_business（WhatsApp Business）| line | tiktok | facebook（Messenger）| instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"unread_count":{"description":"该渠道未读消息数","example":12,"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信未读数汇总","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/conversations/list":{"post":{"description":"查询指定渠道下的私信会话分页列表，支持关键词搜索、未读筛选、AI 标签筛选","operationId":"chuhaijiang-social-im-conversations-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"渠道 ID（必填）。渠道即绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话。通过「私信渠道列表」接口（社媒管理/8.私信管理 分类下）返回的 channel_id 字段获取","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_ids":{"description":"按会话 ID 精确筛选（可多个）","example":["12345"],"items":{"type":"string"},"type":"array"},"filter_marked_unread":{"description":"true 时仅返回手动标注未读的会话；与 keyword 同时使用时本筛选失效","example":false,"type":"boolean"},"filter_tag":{"description":"按 AI 洞察标签筛选：kol（达人）| b2b（B2B 询盘）| buyer（买家）| fan（粉丝）| general（普通）。各标签的会话数见「会话标签计数」接口","enum":["kol","b2b","buyer","fan","general"],"example":"buyer","type":"string"},"filter_unread":{"description":"true 时仅返回有未读消息的会话","example":true,"type":"boolean"},"keyword":{"description":"搜索关键词，匹配会话标题、会话备注；WhatsApp 会话还匹配对方手机号（自动忽略 + 号和空格）。注意：使用 keyword 时 filter_marked_unread 筛选失效","example":"Somchai","type":"string"},"limit":{"description":"每页返回条数（必填），范围 1-50","example":20,"type":"integer"},"offset":{"description":"分页偏移量，从 0 开始，默认 0；第 2 页传 limit×1，第 3 页传 limit×2，以此类推","example":0,"type":"integer"}},"required":["channel_id","limit"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"会话列表，固定排序：置顶会话在前（按置顶时间正序），其余按最后消息时间倒序。会话即渠道与单个联系人（或群）的对话线程。","items":{"properties":{"auto_reply_paused":{"description":"该会话的 AI 自动回复是否被手动暂停","example":false,"type":"boolean"},"avatar":{"description":"会话头像 URL：私聊为对方头像，群聊为群头像","example":"https://cdn.example.com/avatar/xxx.jpg","type":"string"},"channel_id":{"description":"所属渠道 ID","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_id":{"description":"会话 ID（数字字符串），查消息/发消息等接口以此为入参","example":"12345","type":"string"},"external_id":{"description":"平台侧原始会话/联系人标识（如 WhatsApp 手机号）","example":"66812345678","type":"string"},"group_color":{"description":"所属会话分组颜色","example":"#1677ff","type":"string"},"group_id":{"description":"所属会话分组 ID，未分组不返回","example":3,"type":"integer"},"group_name":{"description":"所属会话分组名称","example":"重点跟进","type":"string"},"is_pinned":{"description":"是否置顶","example":false,"type":"boolean"},"labels":{"description":"会话标签列表（点击展开查看详细字段）","items":{"properties":{"color":{"description":"标签颜色","example":"#722ed1","type":"string"},"id":{"description":"标签 ID","example":7,"type":"integer"},"name":{"description":"标签名称","example":"KOL Collab","type":"string"},"tag":{"description":"AI 标签 key：kol/b2b/buyer/fan/general，人工标签为空","example":"kol","type":"string"}},"type":"object"},"type":"array"},"last_message":{"description":"最后一条消息预览，用于列表页展示（点击展开查看详细字段）","properties":{"content":{"description":"消息文本内容；媒体类消息为附言或空","example":"你好，请问这款商品有货吗？","type":"string"},"created_at":{"description":"消息时间（Unix 秒）","example":1783670000,"type":"integer"},"direction":{"description":"消息方向：inbound（对方发来）| outbound（本方发出）","enum":["inbound","outbound"],"example":"inbound","type":"string"},"id":{"description":"消息 ID","example":987654,"type":"integer"},"media":{"description":"媒体内容预览，仅媒体类消息返回（点击展开查看详细字段）","properties":{"filename":{"description":"文件名","example":"photo.jpg","type":"string"},"mime_type":{"description":"MIME 类型","example":"image/jpeg","type":"string"},"type":{"description":"媒体类型","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"媒体访问 URL（有时效）","example":"https://cdn.example.com/im/xxx.jpg","type":"string"}},"type":"object"},"mentions":{"description":"群聊 @ 提及映射，content 中的 @\u003cid\u003e 据此渲染为名称；无提及时不返回（点击展开查看详细字段）","items":{"properties":{"id":{"description":"提及标识（个人为手机号）","example":"8615626176095","type":"string"},"is_all":{"description":"是否为 @所有人","example":false,"type":"boolean"},"name":{"description":"展示名称","example":"张三","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"消息类型：text（文本）| image（图片）| video（视频）| audio（音频）| document（文档）| sticker（表情贴纸）| gif | lottie（动态贴纸）| template（WhatsApp 模板消息）| location（位置）| reaction（表情回应）","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform_message_id":{"description":"平台侧原始消息 ID","example":"wamid.HBgLOD...","type":"string"},"sender_id":{"description":"发送者 ID","example":"66812345678","type":"string"},"sender_name":{"description":"发送者名称","example":"Somchai","type":"string"},"status":{"description":"消息状态：pending（发送中）| sent（已发送）| delivered（已送达）| read（已读）| failed（发送失败）| revoked（已撤回）","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"消息字符串 ID（避免大数值精度丢失），引用回复时使用此值","example":"987654","type":"string"}},"type":"object"},"last_message_at":{"description":"最后消息时间（Unix 秒），列表按此字段倒序排列","example":1783670000,"type":"integer"},"marked_unread":{"description":"是否手动标注未读","example":false,"type":"boolean"},"metadata":{"description":"会话元数据 JSON 字符串（群描述等扩展信息），无则为空","example":"{\"group_description\":\"VIP 客户群\"}","type":"string"},"owner_user_id":{"description":"会话分配的客服用户 ID，空表示未分配","example":"6a7ef569","type":"string"},"pinned_at":{"description":"置顶时间（Unix 秒），未置顶不返回","example":1783600000,"type":"integer"},"platform":{"description":"所属社媒平台：whatsapp（WhatsApp 个人版）| whatsapp_business（WhatsApp Business）| line | tiktok | facebook（Messenger）| instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"remark":{"description":"会话备注（通过「更新会话备注」接口设置）","example":"泰国大客户","type":"string"},"title":{"description":"会话标题：私聊为联系人名称，群聊为群名","example":"Somchai","type":"string"},"type":{"description":"会话类型：1（私聊）| 2（群聊）","enum":[1,2],"example":1,"type":"integer"},"unread_count":{"description":"该会话未读消息数","example":2,"type":"integer"},"window_info":{"description":"消息发送窗口。部分平台限制商家主动发消息的时间窗（如客户最后一条消息后 24 小时内），窗口外发送会失败；调「发送私信」前先检查 can_send_message（点击展开查看详细字段）","properties":{"can_send_message":{"description":"当前是否可发送消息，false 时调「发送私信」会返回窗口关闭错误","example":true,"type":"boolean"},"csw_expires_at":{"description":"WhatsApp Business 专用：24 小时客服窗口过期时间（Unix 秒），其他平台为 0","example":1783746400,"type":"integer"},"fep_expires_at":{"description":"WhatsApp Business 专用：72 小时免费入口窗口（广告引流场景）过期时间（Unix 秒），其他平台为 0","example":0,"type":"integer"},"hours_remaining":{"description":"窗口剩余小时数，负值表示已过期","example":20,"type":"integer"},"last_origin_type":{"description":"WhatsApp Business 专用：会话来源类型（Meta 定义），如 user_initiated（用户主动发起）| marketing（营销消息）| referral_conversion（广告引流）","example":"user_initiated","type":"string"},"messages_sent":{"description":"当前窗口内已发送消息数（限次数窗口用）","example":3,"type":"integer"},"window_expires_at":{"description":"当前窗口过期时间（Unix 秒）","example":1783746400,"type":"integer"},"window_start_time":{"description":"当前窗口开始时间（Unix 秒）","example":1783660000,"type":"integer"},"window_type":{"description":"窗口类型：unlimited（无限制）| 24h（24 小时窗口）| 48h_with_limit（48 小时且限次数）。各平台实际值：WhatsApp 个人版/LINE 为 unlimited，WhatsApp Business/Facebook/Instagram 为 24h，TikTok 为 48h_with_limit（最多 10 条）","enum":["unlimited","24h","48h_with_limit"],"example":"24h","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的会话总数（用于分页）","example":87,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信会话列表","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/conversations/tag-counts":{"post":{"description":"统计指定渠道下各 AI 洞察标签（达人/B2B/买家/粉丝/普通）的会话数量","operationId":"chuhaijiang-social-im-conversation-tag-counts","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"渠道 ID（必填）。渠道即绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话。通过「私信渠道列表」接口（社媒管理/8.私信管理 分类下）返回的 channel_id 字段获取","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},"required":["channel_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"tags":{"description":"各 AI 洞察标签的会话数（标签由系统 AI 自动打标）；固定返回全部 5 个标签，包含计数为 0 的","items":{"properties":{"count":{"description":"该标签下的会话数","example":25,"type":"integer"},"label":{"description":"标签英文显示名（固定值）：KOL Collab | B2B Inquiry | Purchase Intent | Fan Engagement | General","example":"Purchase Intent","type":"string"},"tag":{"description":"标签 key：kol（达人）| b2b（B2B 询盘）| buyer（买家）| fan（粉丝）| general（普通）","enum":["kol","b2b","buyer","fan","general"],"example":"buyer","type":"string"}},"type":"object"},"type":"array"},"total":{"description":"该渠道全部会话数","example":87,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"会话标签计数","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/conversations/{id}":{"post":{"description":"查询单个私信会话详情，含参与者列表和消息发送窗口状态","operationId":"chuhaijiang-social-im-conversation-detail","parameters":[{"description":"会话 ID（数字字符串）。会话即渠道与单个联系人（或群）的对话线程。通过「私信会话列表」接口（社媒管理/8.私信管理 分类下）返回的 conversation_id 字段获取","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"会话详情，比列表条目多参与者信息（点击展开查看详细字段）","properties":{"auto_reply_paused":{"description":"该会话的 AI 自动回复是否被手动暂停","example":false,"type":"boolean"},"avatar":{"description":"会话头像 URL：私聊为对方头像，群聊为群头像","example":"https://cdn.example.com/avatar/xxx.jpg","type":"string"},"channel_id":{"description":"所属渠道 ID","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"conversation_id":{"description":"会话 ID（数字字符串），查消息/发消息等接口以此为入参","example":"12345","type":"string"},"external_id":{"description":"平台侧原始会话/联系人标识（如 WhatsApp 手机号）","example":"66812345678","type":"string"},"last_message":{"description":"最后一条消息预览，用于列表页展示（点击展开查看详细字段）","properties":{"content":{"description":"消息文本内容；媒体类消息为附言或空","example":"你好，请问这款商品有货吗？","type":"string"},"created_at":{"description":"消息时间（Unix 秒）","example":1783670000,"type":"integer"},"direction":{"description":"消息方向：inbound（对方发来）| outbound（本方发出）","enum":["inbound","outbound"],"example":"inbound","type":"string"},"id":{"description":"消息 ID","example":987654,"type":"integer"},"media":{"description":"媒体内容预览，仅媒体类消息返回（点击展开查看详细字段）","properties":{"filename":{"description":"文件名","example":"photo.jpg","type":"string"},"mime_type":{"description":"MIME 类型","example":"image/jpeg","type":"string"},"type":{"description":"媒体类型","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"媒体访问 URL（有时效）","example":"https://cdn.example.com/im/xxx.jpg","type":"string"}},"type":"object"},"mentions":{"description":"群聊 @ 提及映射，content 中的 @\u003cid\u003e 据此渲染为名称；无提及时不返回（点击展开查看详细字段）","items":{"properties":{"id":{"description":"提及标识（个人为手机号）","example":"8615626176095","type":"string"},"is_all":{"description":"是否为 @所有人","example":false,"type":"boolean"},"name":{"description":"展示名称","example":"张三","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"消息类型：text（文本）| image（图片）| video（视频）| audio（音频）| document（文档）| sticker（表情贴纸）| gif | lottie（动态贴纸）| template（WhatsApp 模板消息）| location（位置）| reaction（表情回应）","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform_message_id":{"description":"平台侧原始消息 ID","example":"wamid.HBgLOD...","type":"string"},"sender_id":{"description":"发送者 ID","example":"66812345678","type":"string"},"sender_name":{"description":"发送者名称","example":"Somchai","type":"string"},"status":{"description":"消息状态：pending（发送中）| sent（已发送）| delivered（已送达）| read（已读）| failed（发送失败）| revoked（已撤回）","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"消息字符串 ID（避免大数值精度丢失），引用回复时使用此值","example":"987654","type":"string"}},"type":"object"},"last_message_at":{"description":"最后消息时间（Unix 秒），列表按此字段倒序排列","example":1783670000,"type":"integer"},"owner_user_id":{"description":"会话分配的客服用户 ID，空表示未分配","example":"6a7ef569","type":"string"},"participants":{"description":"会话参与者列表：私聊为对方一人，群聊为全部成员（点击展开查看详细字段）","items":{"properties":{"avatar":{"description":"参与者头像 URL","example":"https://cdn.example.com/avatar/p.jpg","type":"string"},"id":{"description":"参与者 ID（如 WhatsApp 手机号）","example":"66812345678","type":"string"},"is_admin":{"description":"是否群管理员（仅群聊）","example":false,"type":"boolean"},"is_super_admin":{"description":"是否群主（仅群聊）","example":false,"type":"boolean"},"name":{"description":"参与者名称","example":"Somchai","type":"string"}},"type":"object"},"type":"array"},"platform":{"description":"所属社媒平台：whatsapp（WhatsApp 个人版）| whatsapp_business（WhatsApp Business）| line | tiktok | facebook（Messenger）| instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"remark":{"description":"会话备注（通过「更新会话备注」接口设置）","example":"泰国大客户","type":"string"},"title":{"description":"会话标题：私聊为联系人名称，群聊为群名","example":"Somchai","type":"string"},"type":{"description":"会话类型：1（私聊）| 2（群聊）","enum":[1,2],"example":1,"type":"integer"},"unread_count":{"description":"该会话未读消息数","example":2,"type":"integer"},"window_info":{"description":"消息发送窗口。部分平台限制商家主动发消息的时间窗（如客户最后一条消息后 24 小时内），窗口外发送会失败；调「发送私信」前先检查 can_send_message（点击展开查看详细字段）","properties":{"can_send_message":{"description":"当前是否可发送消息，false 时调「发送私信」会返回窗口关闭错误","example":true,"type":"boolean"},"csw_expires_at":{"description":"WhatsApp Business 专用：24 小时客服窗口过期时间（Unix 秒），其他平台为 0","example":1783746400,"type":"integer"},"fep_expires_at":{"description":"WhatsApp Business 专用：72 小时免费入口窗口（广告引流场景）过期时间（Unix 秒），其他平台为 0","example":0,"type":"integer"},"hours_remaining":{"description":"窗口剩余小时数，负值表示已过期","example":20,"type":"integer"},"last_origin_type":{"description":"WhatsApp Business 专用：会话来源类型（Meta 定义），如 user_initiated（用户主动发起）| marketing（营销消息）| referral_conversion（广告引流）","example":"user_initiated","type":"string"},"messages_sent":{"description":"当前窗口内已发送消息数（限次数窗口用）","example":3,"type":"integer"},"window_expires_at":{"description":"当前窗口过期时间（Unix 秒）","example":1783746400,"type":"integer"},"window_start_time":{"description":"当前窗口开始时间（Unix 秒）","example":1783660000,"type":"integer"},"window_type":{"description":"窗口类型：unlimited（无限制）| 24h（24 小时窗口）| 48h_with_limit（48 小时且限次数）。各平台实际值：WhatsApp 个人版/LINE 为 unlimited，WhatsApp Business/Facebook/Instagram 为 24h，TikTok 为 48h_with_limit（最多 10 条）","enum":["unlimited","24h","48h_with_limit"],"example":"24h","type":"string"}},"type":"object"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信会话详情","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/conversations/{id}/messages":{"post":{"description":"查询私信会话的消息记录，支持按类型/时间/关键词筛选，可选拉取时顺带标记会话已读","operationId":"chuhaijiang-social-im-messages-list","parameters":[{"description":"会话 ID（数字字符串）。会话即渠道与单个联系人（或群）的对话线程。通过「私信会话列表」接口（社媒管理/8.私信管理 分类下）返回的 conversation_id 字段获取","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"截止时间（Unix 秒），按消息入库时间筛选该时间之前的消息","example":1783670400,"type":"integer"},"keyword":{"description":"按消息文本内容关键词搜索","example":"订单","type":"string"},"limit":{"description":"每页返回条数（必填），范围 1-50","example":20,"type":"integer"},"mark_as_read":{"description":"true 时本次拉取顺带将该会话标记为已读并清零未读数；同时会向平台发送已读回执（如 WhatsApp 蓝勾），对方可感知已读，请按需使用","example":true,"type":"boolean"},"message_type":{"description":"按消息类型筛选：text（文本）| image（图片）| video（视频）| audio（音频）| document（文档）| sticker（表情贴纸）| gif | lottie（动态贴纸）| template（模板消息）| location（位置）| reaction（表情回应）","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"image","type":"string"},"offset":{"description":"分页偏移量，从 0 开始，默认 0；第 2 页传 limit×1，第 3 页传 limit×2，以此类推","example":0,"type":"integer"},"order":{"description":"排序方向：DESC（新消息在前，默认）| ASC（旧消息在前）","enum":["DESC","ASC"],"example":"DESC","type":"string"},"order_by":{"description":"排序字段：sent_at（发送时间，默认）| created_at（入库时间）","enum":["sent_at","created_at"],"example":"sent_at","type":"string"},"start_time":{"description":"起始时间（Unix 秒），按消息入库时间筛选该时间之后的消息","example":1783584000,"type":"integer"}},"required":["limit"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"data":{"description":"消息列表","items":{"properties":{"channel_id":{"description":"所属渠道 ID","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"content":{"description":"消息文本内容；媒体类消息为附言或空","example":"你好，请问这款商品有货吗？","type":"string"},"conversation_id":{"description":"所属会话 ID","example":"12345","type":"string"},"created_at":{"description":"消息发送时间（平台侧，Unix 秒）；无发送时间时为服务端入库时间","example":1783670000,"type":"integer"},"direction":{"description":"消息方向：inbound（对方发来）| outbound（本方发出）","enum":["inbound","outbound"],"example":"inbound","type":"string"},"error_code":{"description":"发送失败时的平台错误码，成功时不返回","example":"131047","type":"string"},"error_message":{"description":"发送失败时的错误描述，成功时不返回","example":"Re-engagement message","type":"string"},"id":{"description":"消息 ID","example":987654,"type":"integer"},"is_auto_reply":{"description":"是否由 AI 自动回复发出","example":false,"type":"boolean"},"is_imported":{"description":"是否为批量导入的历史消息（非实时收发）","example":false,"type":"boolean"},"media":{"description":"媒体内容，仅媒体类消息返回（点击展开查看详细字段）","properties":{"error_reason":{"description":"媒体不可用的原因说明，仅不可用时返回","example":"media expired","type":"string"},"filename":{"description":"文件名","example":"photo.jpg","type":"string"},"height":{"description":"高度（像素，图片/视频）","example":1920,"type":"integer"},"mime_type":{"description":"MIME 类型","example":"image/jpeg","type":"string"},"status":{"description":"仅媒体不可用时返回 unavailable（如平台侧已过期），可用时不返回本字段","enum":["unavailable"],"example":"unavailable","type":"string"},"type":{"description":"媒体类型","enum":["image","video","audio","document","sticker"],"example":"image","type":"string"},"url":{"description":"媒体访问 URL（签名链接，约 30 天有效期，建议及时转存）","example":"https://cdn.example.com/im/xxx.jpg","type":"string"},"width":{"description":"宽度（像素，图片/视频）","example":1080,"type":"integer"}},"type":"object"},"mentions":{"description":"群聊 @ 提及映射，content 中的 @\u003cid\u003e 按此列表渲染为名称（点击展开查看详细字段）","items":{"properties":{"id":{"description":"提及标识，与 content 中 @\u003cid\u003e 的 \u003cid\u003e 一致（个人为手机号）","example":"8615626176095","type":"string"},"is_all":{"description":"是否为 @所有人","example":false,"type":"boolean"},"name":{"description":"展示名称","example":"张三","type":"string"}},"type":"object"},"type":"array"},"message_type":{"description":"消息类型：text（文本）| image（图片）| video（视频）| audio（音频）| document（文档）| sticker（表情贴纸）| gif | lottie（动态贴纸）| template（WhatsApp 模板消息）| location（位置）| reaction（表情回应）","enum":["text","image","video","audio","document","sticker","gif","lottie","template","location","reaction"],"example":"text","type":"string"},"platform":{"description":"所属社媒平台：whatsapp（WhatsApp 个人版）| whatsapp_business（WhatsApp Business）| line | tiktok | facebook（Messenger）| instagram","enum":["whatsapp","whatsapp_business","line","tiktok","facebook","instagram"],"example":"whatsapp","type":"string"},"platform_message_id":{"description":"平台侧原始消息 ID","example":"wamid.HBgLOD...","type":"string"},"reactions":{"description":"表情回应列表（点击展开查看详细字段）","items":{"properties":{"emoji":{"description":"emoji 字符","example":"👍","type":"string"},"is_self":{"description":"是否本方账号的回应","example":false,"type":"boolean"},"ts":{"description":"回应时间（Unix 秒）","example":1783670100,"type":"integer"},"user_id":{"description":"回应者 ID","example":"66812345678","type":"string"}},"type":"object"},"type":"array"},"reply_to":{"description":"被引用回复的原消息（单层裁剪预览，不含 sentiment/reactions/mentions 等分析字段，不递归嵌套）；非引用消息不返回（点击展开查看详细字段）","properties":{"content":{"description":"被引用消息内容","example":"这款有黑色的吗？","type":"string"},"created_at":{"description":"被引用消息时间（Unix 秒）","example":1783669000,"type":"integer"},"id":{"description":"被引用消息 ID","example":987650,"type":"integer"},"message_type":{"description":"被引用消息类型","example":"text","type":"string"},"sender_name":{"description":"被引用消息发送者","example":"Somchai","type":"string"},"str_id":{"description":"被引用消息字符串 ID","example":"987650","type":"string"}},"type":"object"},"sender_id":{"description":"发送者 ID","example":"66812345678","type":"string"},"sender_name":{"description":"发送者名称","example":"Somchai","type":"string"},"sent_by_platform":{"description":"是否为本方账号在其他客户端（如手机 App）发出的消息","example":false,"type":"boolean"},"sentiment":{"description":"AI 情感分析结果，仅已分析过的消息返回（点击展开查看详细字段）","properties":{"emoji":{"description":"消息意图 emoji","example":"🛒","type":"string"},"insight":{"description":"消息关键洞察摘要","example":"客户有明确购买意向","type":"string"},"insight_label":{"description":"消息意图标签","example":"购买咨询","type":"string"},"key_phrases":{"description":"关键情感短语（最多 5 个）","example":["有货吗"],"items":{"type":"string"},"type":"array"},"label":{"description":"情感标签：positive（积极）| neutral（中性）| negative（消极）| angry（愤怒）","enum":["positive","neutral","negative","angry"],"example":"positive","type":"string"},"score":{"description":"情感得分，-1.0（最消极）～ 1.0（最积极）","example":0.8,"type":"number"},"trend":{"description":"情感趋势：improving（好转）| stable（平稳）| declining（恶化）","example":"stable","type":"string"}},"type":"object"},"status":{"description":"消息状态：pending（发送中）| sent（已发送）| delivered（已送达）| read（已读）| failed（发送失败）| revoked（已撤回）","enum":["pending","sent","delivered","read","failed","revoked"],"example":"read","type":"string"},"str_id":{"description":"消息字符串 ID（避免大数值精度丢失），引用回复时使用此值","example":"987654","type":"string"},"template_info":{"description":"WhatsApp 模板消息信息，仅 message_type=template 时返回（点击展开查看详细字段）","properties":{"components_json":{"description":"模板组件 JSON 字符串（header/body/button 结构）","example":"[{\"type\":\"body\",...}]","type":"string"},"language":{"description":"模板语言代码","example":"zh_CN","type":"string"},"name":{"description":"模板名称","example":"order_confirmation","type":"string"},"status":{"description":"模板审核状态","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"],"example":"APPROVED","type":"string"},"template_id":{"description":"模板 ID","example":101,"type":"integer"}},"type":"object"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的消息总数（用于分页）","example":156,"type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信消息列表","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/im/conversations/{id}/remark":{"post":{"description":"更新私信会话的备注名","operationId":"chuhaijiang-social-im-conversation-remark","parameters":[{"description":"会话 ID（数字字符串）。会话即渠道与单个联系人（或群）的对话线程。通过「私信会话列表」接口（社媒管理/8.私信管理 分类下）返回的 conversation_id 字段获取","in":"path","name":"id","required":true,"schema":{"example":"12345","type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"remark":{"description":"备注内容，传空字符串清除备注；长度上限 255 字符。注意：WhatsApp 私聊的备注会同步为平台侧联系人显示名","example":"泰国大客户，正在谈年框","type":"string"}},"required":["remark"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"操作成功无业务数据返回，以响应信封的 request_id 判断成功","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"更新会话备注","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/im/messages/send":{"post":{"description":"向私信会话发送消息，支持文本、图片、视频、音频、文档及引用回复。发送媒体前先调用「私信上传预签名 URL」接口上传文件。\n\n前置条件：社媒账号的绑定授权需包含私信权限——早期绑定的账号请重新授权绑定；TikTok 仅 Business 类型账号支持私信（个人账号可在 TikTok App 内免费切换为 Business 账号，切换后需重新扫码授权）；Instagram / Facebook 需在出海匠控制台绑定。未满足前置条件时，「私信渠道列表」查不到对应渠道。\n\n注意：发送窗口关闭时返回业务错误码 20510；10 秒内向同一会话重复发送相同内容会命中幂等去重","operationId":"chuhaijiang-social-im-message-send","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content":{"description":"消息文本；text 类型务必提供（服务端不校验，缺省会发出一条空文本消息），媒体类可作为附言（caption）","example":"您好，您咨询的商品有货，今天下单明天发货。","type":"string"},"conversation_id":{"description":"会话 ID（必填）。通过「私信会话列表」接口（社媒管理/8.私信管理 分类下）获取；发送前建议检查该会话 window_info.can_send_message，窗口关闭时发送会失败","example":"12345","type":"string"},"media":{"description":"媒体信息，媒体类消息必填。文件须先通过「私信上传预签名 URL」接口（社媒管理/8.私信管理 分类下）上传（点击展开查看详细字段）","properties":{"filename":{"description":"文件名（含扩展名），必填。不传将导致聊天中显示的文件名退化为无法辨认的存储随机串（如 upload_3f7a1c9e.pdf）","example":"photo.jpg","type":"string"},"height":{"description":"图片/视频高度（像素），选填","example":1920,"type":"integer"},"mime_type":{"description":"MIME 类型，需与上传时一致","example":"image/jpeg","type":"string"},"s3_bucket":{"description":"存储桶名称，取「私信上传预签名 URL」接口返回的 s3_bucket","example":"datanebula-object","type":"string"},"s3_key":{"description":"文件对象 Key，先调用「私信上传预签名 URL」接口（社媒管理/8.私信管理 分类下）上传文件后，取返回的 object_key 填入","example":"im/2026/07/10/20260710153000_photo.jpg","type":"string"},"width":{"description":"图片/视频宽度（像素），选填","example":1080,"type":"integer"}},"required":["filename"],"type":"object"},"mentions":{"description":"群聊 @ 提及的成员手机号列表（纯数字、无 +），仅 WhatsApp 群聊生效，需配合 content 中的 @手机号 文本","example":["8615626176095"],"items":{"type":"string"},"type":"array"},"message_type":{"description":"消息类型（必填）：text（纯文本）| image（图片）| video（视频）| audio（音频）| document（文档）。媒体类须同时传 media 字段","enum":["text","image","video","audio","document"],"example":"text","type":"string"},"reply_to":{"description":"引用回复的目标消息 str_id（从「私信消息列表」的消息条目获取），不引用则不传","example":"987650","type":"string"}},"required":["conversation_id","message_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"data":{"description":"发送成功的完整消息详情，结构与「私信消息列表」的消息条目一致，可直接展示无需再查列表（点击展开查看详细字段）","properties":{"content":{"description":"消息文本内容","example":"您好，您咨询的商品有货，今天下单明天发货。","type":"string"},"conversation_id":{"description":"所属会话 ID","example":"12345","type":"string"},"created_at":{"description":"消息时间（Unix 秒）","example":1783670200,"type":"integer"},"direction":{"description":"消息方向，发送的消息固定为 outbound","example":"outbound","type":"string"},"id":{"description":"消息 ID","example":987655,"type":"integer"},"message_type":{"description":"消息类型","example":"text","type":"string"},"status":{"description":"消息状态","example":"sent","type":"string"},"str_id":{"description":"消息字符串 ID","example":"987655","type":"string"}},"type":"object"},"id":{"description":"消息 ID","example":987655,"type":"integer"},"platform_message_id":{"description":"平台侧原始消息 ID（发送成功后有值）","example":"wamid.HBgLOD...","type":"string"},"status":{"description":"发送状态；发送为同步执行，成功固定返回 sent（送达/已读状态后续以「私信消息列表」查询为准）","example":"sent","type":"string"},"str_id":{"description":"消息字符串 ID（避免大数值精度丢失）","example":"987655","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"发送私信","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/im/upload/presigned-url":{"post":{"description":"生成私信媒体文件的 S3 直传预签名 URL，仅用于私信媒体发送，与通用/加速版文件上传接口不通用。使用流程：1. 调用本接口获取 presigned_url；2. 通过 HTTP PUT 将文件上传到 presigned_url；3. 将返回的 object_key 和 s3_bucket 填入「发送私信」接口的 media 字段","operationId":"chuhaijiang-social-im-upload-presigned-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"文件 MIME 类型，须与后续 PUT 上传时的 Content-Type 请求头一致","example":"image/jpeg","type":"string"},"expires_in":{"description":"预签名 URL 有效期（秒），默认 3600（1 小时），最大 604800（7 天）","example":3600,"type":"integer"},"file_name":{"description":"文件名（含扩展名）","example":"photo.jpg","type":"string"}},"required":["file_name","content_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"cdn_url":{"description":"上传成功后的 CDN 访问地址（可用于自查文件是否上传成功）","example":"https://oss.chuhaijiang.com/im/2026/07/10/20260710153000_photo.jpg","type":"string"},"object_key":{"description":"文件对象 Key（格式 im/年/月/日/时间戳_文件名），上传成功后填入「发送私信」接口（社媒管理/8.私信管理 分类下）的 media.s3_key","example":"im/2026/07/10/20260710153000_photo.jpg","type":"string"},"presigned_url":{"description":"上传预签名 URL：对此 URL 发起 HTTP PUT、请求体为文件二进制、Content-Type 与申请时一致，即完成上传","example":"https://datanebula-object.s3.us-west-2.amazonaws.com/im/2026/07/10/20260710153000_photo.jpg?X-Amz-...","type":"string"},"s3_bucket":{"description":"S3 存储桶名称，填入「发送私信」接口的 media.s3_bucket","example":"datanebula-object","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"私信上传预签名URL","tags":["社媒管理/8.私信管理"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/music/recently-used":{"post":{"description":"获取最近使用的音乐列表","operationId":"chuhaijiang-social-music-recently-used","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"搜索关键词，匹配歌曲名或艺术家","type":"string"},"limit":{"default":20,"description":"每页条数，默认 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"platform_account_id":{"description":"按账号 ID 筛选，仅返回该账号使用过的音乐","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"每页条数","type":"integer"},"music_list":{"items":{"properties":{"artist":{"description":"艺术家/歌手","type":"string"},"commercial_music_id":{"description":"TikTok 商用音乐 ID（用于发布视频时指定背景音乐）","type":"string"},"commercial_music_name":{"description":"歌曲名称","type":"string"},"duration":{"description":"音乐时长（秒）","type":"integer"},"genres":{"description":"音乐风格标签列表","items":{"type":"string"},"type":"array"},"id":{"description":"音乐记录 ID","type":"integer"},"platform_account_id":{"description":"使用此音乐的账号 ID","type":"integer"},"preview_url":{"description":"试听 URL","type":"string"},"song_clip_id":{"description":"歌曲片段 ID（用于精确引用特定片段）","type":"string"},"thumbnail_url":{"description":"封面缩略图 URL","type":"string"},"used_at":{"description":"最近使用时间（Unix 时间戳，秒）","type":"integer"}},"type":"object"},"type":"array"},"page":{"description":"当前页码","type":"integer"},"total_count":{"description":"符合条件的音乐总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"最近使用音乐","tags":["社媒管理/6.创作工具"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/music/search":{"post":{"description":"搜索TikTok热门音乐，支持关键词和类型筛选","operationId":"chuhaijiang-social-music-search","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"country_code":{"description":"国家/地区代码（ISO 3166-1 alpha-2），默认 US","type":"string"},"date_range":{"description":"热门时间范围。可选值：1DAY（当日热门）/ 7DAY（近 7 天）/ 30DAY（近 30 天）","type":"string"},"genre":{"description":"音乐风格筛选。从排行榜数据中动态获取，常见值如 Pop / Hip Hop / Electronic 等","type":"string"},"keyword":{"description":"搜索关键词，匹配歌曲名或艺术家。不传则返回热门音乐排行榜","type":"string"},"limit":{"default":20,"description":"每页条数，默认 20，最大 100","maximum":100,"type":"integer"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"每页条数","type":"integer"},"music_list":{"items":{"properties":{"artist":{"description":"艺术家/歌手","type":"string"},"commercial_music_id":{"description":"TikTok 商用音乐 ID","type":"string"},"commercial_music_name":{"description":"歌曲名称","type":"string"},"country_code":{"description":"所属国家/地区代码","type":"string"},"duration":{"description":"音乐时长（秒）","type":"integer"},"genres":{"description":"音乐风格标签列表","items":{"type":"string"},"type":"array"},"id":{"description":"音乐记录 ID","type":"integer"},"preview_url":{"description":"试听 URL","type":"string"},"rank_position":{"description":"排行榜位置（仅排行榜结果返回）","type":"integer"},"song_clip_id":{"description":"歌曲片段 ID","type":"string"},"thumbnail_url":{"description":"封面缩略图 URL","type":"string"}},"type":"object"},"type":"array"},"page":{"description":"当前页码","type":"integer"},"total_count":{"description":"符合条件的音乐总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"热门音乐搜索","tags":["社媒管理/6.创作工具"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/platform-accounts/detail":{"post":{"description":"获取单个社媒平台账号详细信息","operationId":"chuhaijiang-social-platform-account-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"平台账号ID","type":"integer"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"account":{"properties":{"account_type":{"description":"账号类型：creator（创作者）/ business（商业号）","type":"string"},"avatar_url":{"description":"头像 URL","type":"string"},"created_at":{"description":"绑定时间（Unix 时间戳，秒）","type":"integer"},"display_name":{"description":"账号显示名称","type":"string"},"id":{"description":"账号 ID（系统内部标识）","type":"integer"},"platform":{"description":"平台标识：tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"平台侧账号唯一标识","type":"string"},"region":{"description":"账号所属区域（仅 TikTok Shop 返回，如 US / GB）","type":"string"},"remark":{"description":"用户自定义备注","type":"string"},"scopes":{"description":"OAuth 授权范围列表","items":{"type":"string"},"type":"array"},"status":{"description":"账号状态：active（正常）/ expired（Token 过期）","type":"string"},"updated_at":{"description":"信息更新时间（Unix 时间戳，秒）","type":"integer"},"username":{"description":"平台用户名","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"账号详情","tags":["社媒管理/1.账号管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/platform-accounts/disconnect":{"post":{"description":"解除社媒平台账号绑定","operationId":"chuhaijiang-social-platform-account-disconnect","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"要解绑的账号 ID","format":"int32","type":"integer"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"description":"解绑成功时返回空对象。解绑后该账号的所有 OAuth Token 将被撤销，后续操作（发布、评论等）将失败。","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"解绑社媒账号","tags":["社媒管理/1.账号管理"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/platform-accounts/update-remark":{"post":{"description":"更新社媒平台账号的用户自定义备注","operationId":"chuhaijiang-social-platform-account-update-remark","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"平台账号ID","type":"integer"},"remark":{"description":"备注内容，最大500字符","type":"string"}},"required":["account_id","remark"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"account":{"properties":{"display_name":{"description":"账号显示名称","type":"string"},"id":{"description":"账号 ID","type":"integer"},"remark":{"description":"更新后的备注内容","type":"string"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"更新账号备注","tags":["社媒管理/1.账号管理"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/posts":{"post":{"description":"获取用户发布内容列表，以发布记录为维度，支持多维筛选、排序、数据指标（播放/点赞/评论/分享/GMV 等）。传 platform=tiktok-shop-pc 并按 sort_by=gmv / orders 排序可获取带货视频榜单，start_time / end_time 支持任意统计时间范围。","operationId":"chuhaijiang-social-posts-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"内容类型筛选。可选值：video / image","type":"string"},"end_time":{"description":"日期范围截止，Unix 时间戳（秒），必须与 start_time 同时传","type":"integer"},"include_daily":{"description":"是否返回每条帖子的每日指标序列，需配合 start_time+end_time","type":"boolean"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"page_size":{"default":20,"description":"每页条数，默认 20，最大 50","maximum":50,"type":"integer"},"platform":{"description":"单选平台筛选。可选值：tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"配合 platform_video_id 使用","type":"integer"},"platform_account_ids":{"description":"按账号 ID 列表筛选，不传返回全部","items":{"type":"integer"},"type":"array"},"platform_video_id":{"description":"精确匹配单条帖子（需配合 platform_account_id）","type":"string"},"publication_id":{"description":"精确匹配单条帖子，传了则忽略其他筛选/分页","type":"integer"},"scope":{"default":"published","description":"数据范围。published（默认）：仅区间内发布的帖子+累计指标 / all：区间内有数据变化的所有帖子+区间增量指标。仅传了 start_time+end_time 时生效","type":"string"},"search":{"description":"模糊搜索标题","type":"string"},"sort_by":{"default":"display_time","description":"排序字段。可选值：display_time（默认）/ views / likes / comments / shares / favorites / engagement / gmv / orders","type":"string"},"sort_order":{"default":"desc","description":"排序方向。可选值：desc（默认）/ asc","type":"string"},"start_time":{"description":"日期范围起始，Unix 时间戳（秒）","type":"integer"},"status":{"description":"状态筛选。可选值：published / scheduled / draft / failed / cancelled，不传查全部","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"posts":{"description":"帖子列表","items":{"properties":{"account_avatar_url":{"description":"账号头像 URL","type":"string"},"account_display_name":{"description":"账号名","type":"string"},"account_remark":{"description":"账号备注","type":"string"},"comment_count":{"description":"累计总评论","type":"integer"},"content_type":{"description":"内容类型：video / image","type":"string"},"cover_url":{"description":"封面图 URL","type":"string"},"display_time":{"description":"展示时间戳（Unix 秒）","type":"integer"},"engagement_rate":{"description":"互动率（%）= (likes+comments+shares)/views*100","type":"number"},"error_message":{"description":"错误信息（仅 failed 状态）","type":"string"},"favorite_count":{"description":"累计总收藏","type":"integer"},"gmv":{"description":"总 GMV（仅 tiktok-shop-pc）","type":"number"},"gmv_currency":{"description":"GMV 币种（目前全部 USD）","type":"string"},"last_refreshed_at":{"description":"指标最后刷新时间戳","type":"integer"},"like_count":{"description":"累计总点赞","type":"integer"},"orders":{"description":"订单数（仅 tiktok-shop-pc）","type":"integer"},"platform":{"description":"平台（tiktok / tiktok-shop-pc / instagram / youtube / facebook）","type":"string"},"platform_account_id":{"description":"平台账号 ID","type":"integer"},"platform_url":{"description":"平台原始链接","type":"string"},"platform_video_id":{"description":"平台侧视频 ID（仅 published 状态）","type":"string"},"publication_id":{"description":"发布记录 ID","type":"integer"},"region":{"description":"地区（shop 账号有）","type":"string"},"share_count":{"description":"累计总分享","type":"integer"},"source":{"description":"内容来源","type":"string"},"status":{"description":"状态：published / scheduled / draft / failed / cancelled","type":"string"},"title":{"description":"内容标题","type":"string"},"view_count":{"description":"累计总播放","type":"integer"},"view_trend":{"description":"近 7 天每日播放增量","items":{"type":"integer"},"type":"array"}},"type":"object"},"type":"array"},"total":{"description":"符合条件的总记录数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"发布记录列表","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/posts/refresh":{"post":{"description":"主动触发单条发布记录的平台指标刷新（播放/点赞/评论/分享等），获取当前最新累计值，适用于拉取详情前确保数据新鲜度。注意：本接口刷新的是当前累计指标，不修正历史日级数据。\n\n支持同步与异步两种模式：异步模式（background=true）立即返回，刷新完成后「发布记录详情」的 last_refreshed_at 会前进。\n\n频率限制：同一视频刷新成功后有 60 秒冷却窗口，窗口内重复调用直接返回成功（数据已是最新，不重复请求平台）；异步模式下同一视频刷新进行中时重复调用返回「刷新进行中」；后台队列满时返回 503，请稍后重试；已删除的视频返回 410。","operationId":"chuhaijiang-social-posts-refresh","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"background":{"default":false,"description":"是否异步刷新。true：立即返回，后台拉取平台最新指标，建议轮询「发布记录详情」的 last_refreshed_at 字段判断刷新完成；false 或缺省：同步等待刷新完成后返回","type":"boolean"},"platform_account_id":{"description":"平台账号 ID。来自「社媒账号列表」（社媒管理 \u003e 账号管理）返回的 id 字段","type":"integer"},"platform_video_id":{"description":"平台视频 ID。来自「发布记录列表」（社媒管理 \u003e 视频管理）返回的 platform_video_id 字段","type":"string"}},"required":["platform_video_id","platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"description":"无业务数据字段。请求成功即表示指标刷新已完成（同步模式）或已触发（异步模式），刷新后的最新指标通过「发布记录详情」接口查看","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"刷新发布记录指标","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/publish/cancel":{"post":{"description":"取消特定的发布任务","operationId":"chuhaijiang-social-publish-cancel","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"发布任务ID","type":"integer"}},"required":["publication_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"description":"取消成功时返回空对象。仅 pending / uploading 状态的发布任务可被取消。","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"取消单个发布","tags":["社媒管理/2.视频发布"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/publish/reschedule":{"post":{"description":"修改已排期（scheduled 状态）发布任务的定时发布时间，无需取消重建。仅对通过「上传并发布视频」创建且尚未开始发布的定时任务有效。","operationId":"chuhaijiang-social-publish-reschedule","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"发布任务 ID。来自「上传并发布视频」响应或「发布记录列表」返回的 publication_id，任务必须处于 scheduled（已排期）状态","type":"integer"},"scheduled_at":{"description":"新的定时发布时间（Unix 秒）。必须在当前时间 5 分钟之后、90 天以内","type":"integer"}},"required":["publication_id","scheduled_at"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"description":"无业务数据字段。请求成功即表示改期完成，可通过「发布记录列表」或「发布会话状态」确认新的发布时间","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"调整定时发布时间","tags":["社媒管理/2.视频发布"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/publish/session":{"post":{"description":"查询视频发布会话进度","operationId":"chuhaijiang-social-publish-session","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"session_token":{"description":"发布会话token","type":"string"}},"required":["session_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"publications":{"description":"各发布目标的详细状态","items":{"properties":{"id":{"description":"发布任务 ID","type":"integer"},"platform_url":{"description":"视频在平台上的 URL（发布成功后返回）","type":"string"},"platform_video_id":{"description":"平台侧的视频 ID（发布成功后返回）","type":"string"},"progress_percentage":{"description":"进度百分比（0-100）","type":"integer"},"stage":{"description":"当前阶段描述","type":"string"},"status":{"description":"发布状态：pending / uploading / processing / published / failed / cancelled","type":"string"}},"type":"object"},"type":"array"},"session":{"properties":{"completed_at":{"description":"会话完成时间（Unix 时间戳，秒），进行中时为 null","type":"integer"},"completed_publications":{"description":"已成功完成的数量","type":"integer"},"failed_publications":{"description":"失败的数量","type":"integer"},"id":{"description":"会话 ID","type":"integer"},"session_token":{"description":"会话 Token","type":"string"},"started_at":{"description":"会话开始时间（Unix 时间戳，秒）","type":"integer"},"status":{"description":"会话状态：in_progress（进行中）/ completed（全部完成）/ failed（全部失败）/ cancelled（已取消）","type":"string"},"total_publications":{"description":"发布目标总数","type":"integer"},"video_id":{"description":"关联的视频记录 ID","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"发布会话状态","tags":["社媒管理/2.视频发布"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/publish/session/cancel":{"post":{"description":"取消整个视频发布会话","operationId":"chuhaijiang-social-publish-session-cancel","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"session_token":{"description":"发布会话token","type":"string"}},"required":["session_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"description":"取消成功时返回空对象。将取消该会话下所有尚未完成的发布任务。","properties":{},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"取消发布会话","tags":["社媒管理/2.视频发布"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/publish/upload-and-publish":{"post":{"description":"一站式上传视频并发布到多个社媒平台。","operationId":"chuhaijiang-social-publish-upload","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"bucket_key":{"description":"视频文件路径（从「生成上传预签名URL」接口返回的 object_key 字段获取）。发布单个视频时使用此字段，与 media_items 二选一","type":"string"},"bucket_name":{"description":"视频文件所在的存储桶名称（从「生成上传预签名URL」接口返回的 s3_bucket 字段获取）。发布单个视频时使用此字段，与 media_items 二选一","type":"string"},"content_type":{"default":"video","description":"内容类型。video = 视频（默认），image = 图片/图片轮播","type":"string"},"cover_bucket_key":{"description":"封面图文件路径（可选，从「生成上传预签名URL」接口获取）","type":"string"},"cover_bucket_name":{"description":"封面图存储桶名称（可选，从「生成上传预签名URL」接口获取）","type":"string"},"dry_run":{"default":false,"description":"模拟发布模式。设为 true 时不会实际发布到平台，仅创建发布记录用于测试","type":"boolean"},"duration":{"description":"视频时长（秒），可选。不传时系统会自动检测","type":"number"},"file_size":{"description":"文件大小（字节），可选。不传时系统会自动检测","type":"integer"},"media_items":{"description":"多媒体项列表，用于图片轮播等多文件发布场景。使用此字段时无需传 bucket_name 和 bucket_key。每项通过「生成上传预签名URL」接口上传后获取路径","items":{"properties":{"bucket_key":{"description":"文件路径","type":"string"},"bucket_name":{"description":"文件所在的存储桶名称","type":"string"},"order":{"description":"排序序号（从 1 开始）","type":"integer"}},"required":["bucket_name","bucket_key","order"],"type":"object"},"type":"array"},"publications":{"description":"发布目标列表。支持同时发布到多个账号，每个账号可单独设置标题、描述、标签和定时发布","items":{"properties":{"description":{"description":"发布到平台时的视频描述","type":"string"},"platform_account_id":{"description":"目标社媒账号 ID（从「社媒账号列表」接口获取）","type":"integer"},"platform_config":{"description":"平台特定发布配置（JSON 字符串）。可用字段：\n- privacy (string): 隐私设置。YouTube: public/private(默认)/unlisted；TikTok: PUBLIC_TO_EVERYONE(默认)/MUTUAL_FOLLOW_FRIENDS/FOLLOWER_OF_CREATOR/SELF_ONLY。⚠️ 注意：出海匠用户将 TikTok 账号授权给出海匠时，属于 TikTok Business API 授权（商家授权），因此 privacy 设置不生效，发布后将遵循 TikTok 账号内的默认隐私设置（作为对比，is_aigc AI 生成内容声明会正常生效）\n- disable_comment (boolean): 禁用评论（仅 TikTok，不含 TikTok Shop 挂车发布）\n- disable_duet (boolean): 禁用合拍（仅 TikTok 视频，不含 TikTok Shop 挂车发布）\n- disable_stitch (boolean): 禁用合集（仅 TikTok 视频，不含 TikTok Shop 挂车发布）\n- is_aigc (boolean): AI 生成内容声明（仅 TikTok 商家授权账号视频发布和图文发布，不含 TikTok Shop 挂车发布）\n- music_sound_id (string): 指定 TikTok 商家授权账号使用的商用音乐片段。填写「热门音乐搜索」或「最近使用音乐」接口返回的 song_clip_id。支持视频和图文；不适用于 TikTok Personal 或 TikTok Shop 挂车发布\n- music_sound_volume (integer): 音乐音量，范围 0-100，默认 100（仅 TikTok 商家授权账号视频）\n- music_sound_start (integer): 音乐片段开始时间，单位毫秒，必须大于或等于 0（仅 TikTok 商家授权账号视频）\n- music_sound_end (integer): 音乐片段结束时间，单位毫秒，必须大于或等于 0；与 music_sound_start 同时传入时必须大于开始时间（仅 TikTok 商家授权账号视频）\n- video_original_sound_volume (integer): 原视频声音音量，范围 0-100（仅 TikTok 商家授权账号视频）\n- auto_add_music (boolean): 由 TikTok 自动添加音乐（仅 TikTok 商家授权账号图文发布）。图文发布时与 music_sound_id 二选一，不要同时传入\n- product_id (string): 关联商品 ID（仅 TikTok Shop）\n- product_title (string): 关联商品名称（仅 TikTok Shop，与 product_id 配合使用）\n\n⚠️ 重要：传入 product_id 后将走 TikTok Shop 挂车发布链路，privacy/disable_comment/disable_duet/disable_stitch/is_aigc 及上述 TikTok 商家授权账号音乐配置均不生效，评论等设置将遵循 TikTok 账号内的默认设置。\n\n示例：{\"privacy\":\"PUBLIC_TO_EVERYONE\",\"is_aigc\":true,\"music_sound_id\":\"7512345678901234567\",\"music_sound_volume\":80,\"video_original_sound_volume\":20}","type":"string"},"scheduled_at":{"description":"定时发布时间（Unix 时间戳，秒）。不传则立即发布","type":"integer"},"tags":{"description":"标签列表（如 [\"#fyp\", \"#viral\"]）","items":{"type":"string"},"type":"array"},"title":{"description":"发布到平台时的视频标题","type":"string"}},"required":["platform_account_id","title"],"type":"object"},"type":"array"},"video_description":{"description":"视频描述，将显示在发布记录中","type":"string"},"video_title":{"description":"视频标题，将显示在发布记录中","type":"string"}},"required":["video_title","publications"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":10}},"schema":{"properties":{"data":{"properties":{"session_token":{"description":"发布会话 Token。用于通过「发布会话状态」接口轮询发布进度","type":"string"},"skipped_accounts":{"description":"因频率限制被跳过的账号信息列表。正常情况下为空数组","items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"上传并发布视频","tags":["社媒管理/2.视频发布"],"x-billing-mode":"per_call","x-coin-cost":10,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/seller/daily-report":{"post":{"description":"单店经营日报：昨日战报（GMV/订单/客单价/退款/销冠商品，订单实时口径）、退货与库存信号（含约 X 天售罄预估）、经营分析（访客/转化/GMV 渠道结构/单品转化漏斗/GMV 归因/滞销品，T-2 口径）、AI 经营建议（焦点提示/1-3 条行动建议/一句话点评）、店铺风险板块与 7 天趋势。需先完成 TikTok Shop 卖家授权。\n\n工作机制：本接口读取预生成的报告缓存（同一店铺同一日期的报告生成后缓存 26 小时）。status=ready 返回完整数据；status=generating 表示后台生成中，建议 5-10 秒后重试。\n\n计费说明：按调用次数计费，generating 状态的调用同样计费。建议拉取报告后自行缓存复用。\n\n排查提示：若长时间处于 generating，请检查 ① platform_account_id 是否为 TikTok Shop 卖家账号且属于当前用户；② date 格式是否严格为 YYYY-MM-DD——以上错误不会返回报错，但报告无法生成。","operationId":"chuhaijiang-seller-daily-report","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"date":{"description":"报告日期，格式必须严格为 YYYY-MM-DD（如 2026-07-09），通常传昨天。格式错误不会报错，但报告会始终处于 generating 状态。战报数据为该日实时订单口径，经营分析为 T-2 口径","type":"string"},"platform_account_id":{"description":"卖家店铺账号 ID（来自「社媒账号列表」，必须为 TikTok Shop 卖家账号）。注意：传入非卖家账号或无权访问的账号不会报错，但报告会始终处于 generating 状态","type":"integer"}},"required":["platform_account_id","date"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":5}},"schema":{"properties":{"data":{"properties":{"data":{"description":"日报数据，仅 status=ready 时返回（点击展开查看详细字段）","properties":{"advice":{"description":"AI 经营建议（点击展开查看详细字段）","properties":{"focus_line":{"description":"焦点提示（16 字以内）","type":"string"},"from_llm":{"description":"是否由 AI 生成（false 表示 AI 失败时的规则版回退）","type":"boolean"},"insight":{"description":"一句话经营点评，可能为空","type":"string"},"suggestions":{"description":"1-3 条行动建议","items":{"type":"string"},"type":"array"}},"type":"object"},"analytics":{"description":"经营分析（T-2 口径，可能为空）：访客/转化/页面浏览、视频带货、GMV 渠道结构（直播/视频/商品卡）、销冠单品转化漏斗、GMV 归因分解、高曝光低转化滞销品","type":"object"},"battle":{"description":"昨日战报（订单实时口径）（点击展开查看详细字段）","properties":{"aov":{"description":"客单价","type":"string"},"currency":{"description":"币种","type":"string"},"gmv":{"description":"当日销售额","type":"string"},"gmv_change":{"description":"GMV 环比（如 +8.5%），前一日无数据时为空","type":"string"},"items":{"description":"出件数","type":"integer"},"orders":{"description":"有效（已付）订单数","type":"integer"},"refund_amount":{"description":"退款金额","type":"string"},"refund_count":{"description":"当日新发起退款单数","type":"integer"},"top_products":{"description":"销冠商品（含 GMV/件数/售价/主图/库存告急提示）","items":{"type":"object"},"type":"array"}},"type":"object"},"battle_date":{"description":"战报口径日期","type":"string"},"risk":{"description":"店铺风险板块（资质/商品状态/退款率/结算），无风险时为空","type":"object"},"shop_name":{"description":"店铺名称","type":"string"},"signals":{"description":"退货与库存信号（点击展开查看详细字段）","properties":{"inventory":{"description":"昨日有售商品的库存状况（总库存/最少 SKU 库存/断货 SKU 数/约 X 天售罄预估）","items":{"type":"object"},"type":"array"},"refunds":{"description":"按 SKU 聚合的退货（含最常见退货原因）","items":{"type":"object"},"type":"array"}},"type":"object"},"trend":{"description":"近 7 天 GMV 与访客趋势（含连涨/连跌标注）。访客为 -1 表示该日数据未出","type":"object"}},"type":"object"},"status":{"description":"报告状态：ready（就绪，data 有值）/ generating（后台生成中，建议 5-10 秒后重试；若长时间不变请检查账号与日期参数）","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺经营日报","tags":["社媒管理/9.店铺经营"],"x-billing-mode":"per_call","x-coin-cost":5,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/seller/shop-products":{"post":{"description":"查询已绑定 TikTok Shop 卖家店铺的商品列表，支持关键词搜索与排序。返回商品标题、主图、价格、状态、所属店铺等。需先在出海匠完成 TikTok Shop 卖家授权（与达人账号授权不同）。商品的 SKU 明细与数值库存请用「店铺商品详情」查询。","operationId":"chuhaijiang-seller-shop-products","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"商品标题搜索关键词（模糊匹配）","type":"string"},"page":{"default":1,"description":"页码，默认 1","type":"integer"},"page_size":{"default":10,"description":"每页数量，默认 10，最大 50","maximum":50,"type":"integer"},"platform_account_id":{"description":"卖家店铺账号 ID（来自「社媒账号列表」，账号类型为 TikTok Shop 卖家）。不传则查询当前用户所有卖家店铺的商品","type":"integer"},"sort_by":{"default":"update_time","description":"排序字段。可选值：update_time（更新时间，默认）/ create_time（创建时间）/ price（价格）/ title（标题）。传入其他值时按默认 update_time 处理（不报错）","type":"string"},"sort_order":{"default":"desc","description":"排序方向。可选值：desc（降序，默认）/ asc（升序）。传入其他值时按 desc 处理","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"products":{"description":"商品列表（点击展开查看详细字段）","items":{"properties":{"category":{"description":"顶级分类名，未补全时为空","type":"string"},"create_time":{"description":"商品创建时间（Unix 秒）","type":"integer"},"image_url":{"description":"商品主图 URL（临时签名链接），图片未同步时为空","type":"string"},"platform_account_id":{"description":"所属卖家账号 ID","type":"integer"},"price":{"description":"价格（首个 SKU 的售价）","type":"number"},"price_currency":{"description":"价格币种","type":"string"},"product_id":{"description":"商品 ID，用于「店铺商品详情」查询","type":"string"},"shop_name":{"description":"所属店铺名称","type":"string"},"shop_region":{"description":"所属店铺区域（如 US / BR / MX）","type":"string"},"status":{"description":"商品状态：ACTIVATE（在售）/ SELLER_DEACTIVATED（卖家下架）/ DELETED（已删除）","type":"string"},"title":{"description":"商品标题","type":"string"},"update_time":{"description":"商品更新时间（Unix 秒）","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"商品总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺商品列表","tags":["社媒管理/9.店铺经营"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/seller/shop-products/detail":{"post":{"description":"查询卖家店铺单个商品的完整详情：富文本描述、全部商品图、完整分类链，以及 SKU 明细（含每个 SKU 的价格与**数值库存**）。数据实时查询 TikTok Shop 卖家官方接口（非缓存）。需先完成 TikTok Shop 卖家授权。商品不存在或不属于该店铺时返回系统错误。","operationId":"chuhaijiang-seller-shop-product-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"卖家店铺账号 ID（来自「社媒账号列表」）","type":"integer"},"product_id":{"description":"商品 ID，来自「店铺商品列表」返回的 product_id","type":"string"}},"required":["platform_account_id","product_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"category":{"description":"完整分类链，如 Sports \u0026 Outdoor \u003e Fitness \u003e ...","type":"string"},"create_time":{"description":"创建时间（Unix 秒）","type":"integer"},"description":{"description":"商品富文本描述（HTML）","type":"string"},"images":{"description":"全部商品图（点击展开查看详细字段）","items":{"properties":{"height":{"description":"高度（像素）","type":"integer"},"url":{"description":"图片 URL","type":"string"},"width":{"description":"宽度（像素）","type":"integer"}},"type":"object"},"type":"array"},"product_id":{"description":"商品 ID","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"shop_region":{"description":"店铺区域","type":"string"},"skus":{"description":"SKU 列表，含价格与数值库存（点击展开查看详细字段）","items":{"properties":{"inventory":{"description":"该 SKU 当前库存数量（实时值，为该 SKU 全部仓库库存合计）","type":"integer"},"price":{"description":"该 SKU 价格","type":"number"},"price_currency":{"description":"币种","type":"string"},"seller_sku":{"description":"卖家自定义 SKU 编码","type":"string"},"sku_id":{"description":"SKU ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"商品状态：ACTIVATE / SELLER_DEACTIVATED / DELETED","type":"string"},"title":{"description":"商品标题","type":"string"},"update_time":{"description":"更新时间（Unix 秒）","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺商品详情","tags":["社媒管理/9.店铺经营"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/seller/shops-overview":{"post":{"description":"多店汇总经营概览：GMV/订单/售出件数（含环比）、视频播放与 GPM、日均访客与转化率，以及每个店铺的明细（按 GMV 降序，含每日 GMV 序列）。数据来自 TikTok Shop 卖家官方接口，statistics 数据有 1-2 天延迟（以 data_available_date 为准）。需先完成 TikTok Shop 卖家授权。","operationId":"chuhaijiang-seller-shops-overview","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currency":{"default":"USD","description":"币种模式，仅支持 USD（默认，跨店汇总为美元）/ LOCAL（各店按本地币种返回）。注意：summary 汇总块仅在各店铺返回币种一致时出现","type":"string"},"end_date":{"description":"统计结束日期 YYYY-MM-DD（含），默认今天。须与 start_date 成对传入","type":"string"},"start_date":{"description":"统计开始日期 YYYY-MM-DD（含），默认昨天。须与 end_date 成对传入，只传其中一个时按默认区间处理","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"connected_shops":{"description":"其中授权有效（active）的店铺数","type":"integer"},"currency":{"description":"统一币种（如 USD）；各店币种不一致时为空","type":"string"},"current_period":{"description":"实际统计周期。以 TikTok 数据实际可用日期为准，可能早于请求的日期（点击展开查看详细字段）","properties":{"end_date":{"description":"周期截止日 YYYY-MM-DD（含，为数据实际可用的最后一天）","type":"string"},"start_date":{"description":"周期起始日 YYYY-MM-DD（含）","type":"string"}},"type":"object"},"data_available_date":{"description":"TikTok Shop 数据实际可用的截止日期（statistics 数据有 1-2 天延迟）","type":"string"},"previous_period":{"description":"环比对比周期（点击展开查看详细字段）","properties":{"end_date":{"description":"周期截止日","type":"string"},"start_date":{"description":"周期起始日","type":"string"}},"type":"object"},"shops":{"description":"各店铺明细，按 GMV 降序（点击展开查看详细字段）","items":{"properties":{"avg_conversion_rate":{"description":"日均转化率（0.0435 = 4.35%）","type":"number"},"avg_visitors":{"description":"日均访客数","type":"integer"},"daily_gmv":{"description":"周期内每日 GMV 数组（按日期升序），可用于绘制趋势","items":{"type":"number"},"type":"array"},"gmv":{"description":"周期内 GMV","type":"number"},"gmv_change_rate":{"description":"GMV 环比变化率","type":"number"},"gmv_currency":{"description":"币种","type":"string"},"gmv_share":{"description":"占总 GMV 比例（0.675 = 67.5%）","type":"number"},"items_sold":{"description":"售出件数","type":"integer"},"items_sold_change_rate":{"description":"售出件数环比变化率","type":"number"},"orders":{"description":"订单数","type":"integer"},"orders_change_rate":{"description":"订单环比变化率","type":"number"},"platform_account_id":{"description":"店铺账号 ID","type":"integer"},"product_count":{"description":"店铺商品数量","type":"integer"},"shop_name":{"description":"店铺名称","type":"string"},"shop_region":{"description":"店铺区域：US / BR / MX 等","type":"string"},"status":{"description":"授权状态：active / expired / revoked","type":"string"}},"type":"object"},"type":"array"},"summary":{"description":"多店汇总，仅当各店铺币种一致时返回（点击展开查看详细字段）","properties":{"gmv":{"description":"全部店铺 GMV 合计","type":"number"},"gmv_change_rate":{"description":"GMV 环比变化率（0.15 = +15%）","type":"number"},"gmv_currency":{"description":"汇总币种","type":"string"},"gpm":{"description":"千次播放成交额 = GMV / 播放 × 1000","type":"number"},"items_sold":{"description":"售出件数合计","type":"integer"},"items_sold_change_rate":{"description":"售出件数环比变化率","type":"number"},"orders":{"description":"订单合计","type":"integer"},"orders_change_rate":{"description":"订单环比变化率","type":"number"},"video_views":{"description":"全部店铺视频总播放量","type":"integer"},"video_views_change_rate":{"description":"视频播放量环比变化率","type":"number"}},"type":"object"},"total_shops":{"description":"已绑定的卖家店铺总数（含授权过期的）","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"店铺经营总览","tags":["社媒管理/9.店铺经营"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/tiktok-shop/auth-url":{"get":{"description":"生成 TikTok Shop（挂车/店铺达人）网页授权链接，用于绑定挂车账号，适合账号持有人不在身边的场景（如云手机、代运营）。\n\n绑定达人橱窗号时无需传 `type`（默认跨境档）；绑定店铺/渠道号时按店铺所在区域传 `type`。\n\n将返回的 `auth_url` 发送给店铺达人账号持有人，在任意浏览器打开并登录确认授权后，该账号会自动绑定到您的团队——无需轮询任何状态接口，稍后调用「社媒账号列表」即可看到新绑定的账号。\n\n注意：链接长期有效且可重复使用，任何人打开并完成授权都会将其账号绑定到您的团队，请仅发送给可信的账号持有人。","operationId":"social-tiktok-shop-auth-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"店铺区域档位，默认 `cross-border`。`cross-border`=跨境店铺（美国、巴西、墨西哥）及达人橱窗号；`mx-local`=墨西哥本土店铺（同跨境档）；`domestic`=美国本土店铺；`local-jp`=日本本土店铺；`local-eu`=欧洲本土店铺（德国、西班牙、法国、英国、爱尔兰、意大利，同日本档）","in":"query","name":"type","required":false,"schema":{"enum":["cross-border","mx-local","domestic","local-jp","local-eu"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"auth_url":"https://shop.tiktok.com/alliance/creator/auth?app_key=6a...\u0026state=chj:prod:chj:9f8e...:eyJ1aWQ...af46","state":"chj:prod:chj:9f8e...:eyJ1aWQ...af46"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_url":{"description":"TikTok Shop 达人授权页完整链接。发送给店铺达人账号持有人在任意浏览器打开，登录并确认授权后账号自动绑定","type":"string"},"state":{"description":"授权链接中的防篡改签名串（已包含在 auth_url 内，一般无需单独使用）","type":"string"}},"required":["auth_url","state"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"获取TikTok Shop授权链接","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok-shop/products":{"post":{"description":"获取TikTok Shop统一商品列表，自动路由橱窗/店铺商品","operationId":"chuhaijiang-social-tiktok-shop-products","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"TikTok Shop 账号 ID","type":"integer"},"data_source":{"description":"数据来源。可选值：shop（店铺全部商品）/ showcase（橱窗商品）","type":"string"},"origin":{"description":"商品来源筛选。可选值：LIVE（直播）/ SHOWCASE（橱窗）","type":"string"},"page_size":{"default":20,"description":"每页条数，范围 1-20，默认 20","maximum":20,"minimum":1,"type":"integer"},"page_token":{"description":"翻页 Token。首次不传，后续传入上一次响应的 next_page_token","type":"string"},"sort_field":{"description":"排序字段。可选值：PRODUCT_ID / PRICE / SALE","type":"string"},"sort_order":{"description":"排序方向。可选值：DESC（降序）/ ASC（升序）","type":"string"},"title_keyword":{"description":"商品标题搜索关键词","type":"string"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"creator_type":{"description":"创作者类型","type":"string"},"data_source":{"description":"数据来源","type":"string"},"next_page_token":{"description":"下一页 Token。为空表示已到最后一页","type":"string"},"products":{"items":{"properties":{"added_status":{"description":"橱窗添加状态","type":"string"},"brand_name":{"description":"品牌名称","type":"string"},"commission":{"description":"佣金信息","properties":{"amount":{"description":"佣金金额","type":"string"},"rate":{"description":"佣金比例（%）","type":"number"}},"type":"object"},"detail_link":{"description":"商品详情页链接","type":"string"},"id":{"description":"商品 ID","type":"string"},"images":{"description":"商品图片列表","items":{"properties":{"height":{"description":"图片高度（像素）","type":"integer"},"url":{"description":"图片 URL","type":"string"},"width":{"description":"图片宽度（像素）","type":"integer"}},"type":"object"},"type":"array"},"inventory_status":{"description":"库存状态","type":"string"},"is_hidden":{"description":"是否在橱窗中隐藏","type":"boolean"},"price":{"description":"商品价格","properties":{"amount":{"description":"价格金额","type":"string"},"currency":{"description":"货币单位","type":"string"}},"type":"object"},"review_status":{"description":"审核状态","type":"string"},"sale_regions":{"description":"销售区域列表（如 US / GB）","items":{"type":"string"},"type":"array"},"sales_count":{"description":"累计销量","type":"integer"},"shop_name":{"description":"所属店铺名称","type":"string"},"source":{"description":"商品来源","type":"string"},"title":{"description":"商品名称","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"商品总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok商品列表","tags":["社媒管理/7.TikTok Shop"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/tiktok-shop/showcase/add":{"post":{"description":"向TikTok Shop创作者橱窗添加商品","operationId":"chuhaijiang-social-tiktok-shop-showcase-add","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"平台账号ID","type":"integer"},"add_type":{"description":"添加方式：PRODUCT_ID/PRODUCT_LINK","type":"string"},"product_ids":{"description":"商品ID列表，最多20个","items":{"type":"string"},"type":"array"},"product_link":{"description":"商品链接","type":"string"}},"required":["account_id","add_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":2}},"schema":{"properties":{"data":{"properties":{"errors":{"description":"添加失败的商品列表。为空数组表示全部成功","items":{"properties":{"code":{"description":"错误代码","type":"integer"},"message":{"description":"错误原因描述","type":"string"},"product_id":{"description":"添加失败的商品 ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"添加橱窗商品","tags":["社媒管理/7.TikTok Shop"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/auth-url":{"get":{"description":"生成 TikTok 网页授权链接，是扫码之外的另一种账号绑定方式，适合账号持有人不在身边的场景（如云手机、代运营）。\n\n将返回的 `auth_url` 发送给 TikTok 账号持有人，在任意浏览器打开并登录确认授权后，该账号会自动绑定到您的团队——无需轮询任何状态接口，稍后调用「社媒账号列表」即可看到新绑定的账号。\n\n注意：链接长期有效且可重复使用，任何人打开并完成授权都会将其 TikTok 账号绑定到您的团队，请仅发送给可信的账号持有人。","operationId":"social-tiktok-auth-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"auth_url":"https://www.tiktok.com/v2/auth/authorize?client_key=aw...\u0026scope=...\u0026response_type=code\u0026redirect_uri=...\u0026state=ttweb%3A...","ref":"bind_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUu0","state":"ttweb:9f8e...:eyJ1aWQ...af46"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_url":{"description":"TikTok 授权页完整链接。发送给账号持有人在任意浏览器打开，登录并确认授权后账号自动绑定","type":"string"},"ref":{"description":"本次授权的绑定关联标识，以 bind_ 开头，可用于查询该次授权绑定的账号。","type":"string"},"state":{"description":"授权链接中的防篡改签名串（已包含在 auth_url 内，一般无需单独使用）","type":"string"}},"required":["auth_url","state","ref"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"获取TikTok授权链接","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/bind-status":{"post":{"description":"凭“获取 TikTok 授权链接”返回的 ref 查询 OAuth 绑定回执。绑定成功返回账号信息；尚未授权、回执过期或 Redis best-effort 写入失败均返回 pending。建议轮询间隔不低于 3 秒，返回 bound 后停止轮询。","operationId":"chuhaijiang-social-tiktok-bind-status","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ref":{"description":"从获取 TikTok 授权链接接口获得的授权回执标识；必须原样传入。","type":"string","x-notes":["ref 是不透明的关联标识，不是 TikTok 账号 ID。","请从 GET /open/v1/social/tiktok/auth-url 的成功响应取得；不要自行生成、修改或拼接。"]}},"required":["ref"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"account":{"description":"本次授权绑定的 TikTok 账号信息；仅在 status 为 bound 时返回。（点击展开查看详细字段）","properties":{"display_name":{"description":"个人主页展示昵称。","type":"string"},"platform":{"description":"平台，当前为 tiktok。","enum":["tiktok"],"type":"string"},"platform_account_id":{"description":"TikTok 平台账号 ID（openID），用于识别本次绑定的是哪个账号。","type":"string"},"username":{"description":"账号唯一用户名 / Handle，例如 @creator_name，用于主页链接、搜索和区分账号。","type":"string"}},"required":["platform","username","display_name","platform_account_id"],"type":"object","x-notes":["pending 状态不会返回 account；请仅在 bound 状态下读取其中字段。"]},"base_resp":{"description":"绑定回执查询结果。（点击展开查看详细字段）","properties":{"code":{"description":"查询结果码。0 表示查询成功；非 0 表示本次查询暂时失败，可稍后重试。","type":"integer"},"msg":{"description":"查询结果消息，用于辅助诊断；请勿将其作为稳定的业务状态判断。","type":"string"}},"required":["msg","code"],"type":"object","x-notes":["判断绑定是否成功请以 status 为准；当 code 非 0 时，建议将本次查询视为暂时失败并稍后重试。"]},"status":{"description":"授权绑定回执状态。","enum":["pending","bound"],"type":"string"}},"required":["status","base_resp"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询 TikTok 授权绑定状态","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/qrcode":{"post":{"description":"获取TikTok扫码登录二维码。⚠️ 重要：获取二维码后必须立即开始轮询「TikTok扫码状态查询」接口（每2~3秒，直到返回 status=confirmed/utilised），不要等扫码后才开始轮询——从未被查询过状态的二维码，扫码时会直接提示二维码已过期。\n当前接口绑定的是普通社媒账号；如需绑定带货（挂车）账号，请使用「获取TikTok Shop授权链接」接口完成授权，绑定后即可通过API发布挂车视频。","operationId":"chuhaijiang-social-tiktok-qrcode","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"connector":{"description":"连接器标识，固定传 \"chj\"","enum":["chj"],"type":"string"},"state":{"description":"可选的 CSRF 防护参数。传入后会在扫码确认时原样返回，用于验证回调来源的合法性","type":"string"}},"required":["connector"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"scan_qrcode_url":{"description":"二维码图片 URL，展示给用户用 TikTok App 扫码","type":"string"},"token":{"description":"扫码会话 Token，用于调用「TikTok扫码状态查询」接口轮询扫码结果。拿到本响应后请立即开始轮询（每2~3秒），不要等扫码后才查询","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok扫码登录","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/qrcode/check":{"post":{"description":"轮询TikTok扫码登录状态。⚠️ 获取二维码后请立即开始轮询本接口（每2~3秒），不要等扫码后才开始——从未被查询过状态的二维码，扫码时会直接提示二维码已过期","operationId":"chuhaijiang-social-tiktok-qrcode-check","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"connector":{"description":"连接器标识，固定传 \"chj\"","enum":["chj"],"type":"string"},"token":{"description":"从「TikTok扫码登录」接口获取的 token","type":"string"}},"required":["connector","token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"account":{"description":"绑定成功时返回的账号信息（status=confirmed 且连接成功时）","properties":{"account_type":{"description":"账号类型：business/creator","type":"string"},"avatar_url":{"description":"头像URL","type":"string"},"created_at":{"description":"绑定时间（Unix时间戳）","type":"integer"},"display_name":{"description":"显示名称","type":"string"},"id":{"description":"账号ID","type":"integer"},"platform":{"description":"平台","type":"string"},"platform_account_id":{"description":"平台侧账号ID","type":"string"},"region":{"description":"TikTok Shop 区域","type":"string"},"scopes":{"description":"OAuth 授权范围","items":{"type":"string"},"type":"array"},"status":{"description":"账号状态：active/expired/revoked","type":"string"},"username":{"description":"用户名","type":"string"}},"type":"object"},"status":{"description":"授权状态机：new(待扫码) → scanned(已扫码，待在 TikTok App 内确认) → confirmed(已确认授权，出海匠自动完成授权码兑换与账号绑定) → utilised(授权码已核销，绑定已完成)；未确认前二维码过期则进入 expired。轮询时只需关注此字段：expired 请重新调用「TikTok扫码登录」接口生成新二维码；confirmed/utilised 均表示绑定完成，请停止轮询并调用「社媒账号列表」接口确认新账号。注意：轮询间隔内可能错过 confirmed 直接看到 utilised，属正常现象","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"TikTok扫码状态查询","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/upload/presigned-url":{"post":{"description":"生成S3预签名上传URL，用于客户端直传文件\n\n使用流程：\n1. 调用本接口获取 presigned_url 和 cdn_url\n2. 使用 presigned_url 通过 HTTP PUT 上传文件（见下方示例）\n3. 上传完成后，cdn_url 即可访问\n\nStep 2 上传示例：\ncurl --request PUT \\\n  --header \"Content-Type: image/jpeg\" \\\n  --data-binary @\"your_file.jpg\" \\\n  \"{presigned_url}\"","operationId":"chuhaijiang-social-upload-presigned-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"文件 MIME 类型。如 video/mp4、image/jpeg、image/png","type":"string"},"expires_in":{"description":"预签名 URL 有效期（秒），默认 3600（1小时）","type":"integer"},"file_name":{"description":"文件名（含扩展名），如 \"video.mp4\" 或 \"cover.jpg\"","type":"string"},"region":{"description":"存储区域。可选值：tos（亚太区，默认）/ aws（美区）。选择离目标发布平台更近的区域可提升上传速度","type":"string"}},"required":["file_name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"cdn_url":{"description":"文件的 CDN 访问地址（上传完成后可用）","type":"string"},"object_key":{"description":"文件路径。在调用「上传并发布视频」接口时传入 bucket_key 字段","type":"string"},"presigned_url":{"description":"预签名上传 URL。使用 HTTP PUT 方法上传文件到此 URL","type":"string"},"s3_bucket":{"description":"存储桶名称。在调用「上传并发布视频」接口时传入 bucket_name 字段","type":"string"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"生成上传预签名URL","tags":["文件上传"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/videos/check-info":{"post":{"description":"上传前校验视频是否符合各平台规则","operationId":"chuhaijiang-social-video-check-info","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"bucket_name":{"description":"存储桶名（从「通用」分类下的「生成上传预签名URL」接口返回的 s3_bucket）","type":"string"},"object_key":{"description":"文件路径（从「通用」分类下的「生成上传预签名URL」接口返回的 object_key）","type":"string"}},"required":["bucket_name","object_key"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"platform_rules":{"additionalProperties":{"type":"object"},"description":"各平台的视频规则要求（时长、分辨率、文件大小限制等）","type":"object"},"validation_results":{"additionalProperties":{"properties":{"errors":{"description":"校验错误列表（is_valid=false 时返回）","items":{"properties":{"field":{"description":"不合规的字段（如 duration / resolution / file_size）","type":"string"},"reason":{"description":"不合规的具体原因","type":"string"}},"type":"object"},"type":"array"},"is_valid":{"description":"该平台是否校验通过","type":"boolean"}},"type":"object"},"description":"各平台的校验结果。key 为平台标识（tiktok / instagram / youtube 等）","type":"object"},"video_metadata":{"description":"视频文件元数据","properties":{"bit_rate":{"description":"比特率（bps）","type":"integer"},"codec_name":{"description":"视频编码格式（如 h264 / hevc）","type":"string"},"duration":{"description":"视频时长（秒）","type":"number"},"file_size":{"description":"文件大小（字节）","type":"integer"},"frame_rate":{"description":"帧率（fps）","type":"number"},"height":{"description":"视频高度（像素）","type":"integer"},"width":{"description":"视频宽度（像素）","type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频信息校验","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/videos/detail":{"post":{"description":"查询单条发布记录的完整详情：基础信息、累计社媒指标（播放/点赞/评论/分享/收藏/互动率）、最近 30 天日级指标时序、平台特有扩展指标（TikTok 完播率/触达/受众分布等 19 项，Instagram 触达/观看时长）、带货数据（GMV/订单/售出件数/30 天带货时序/关联商品/锚点展示率/点击率）。支持 publication_id 或 platform_video_id + platform_account_id 两种定位方式。\n\n【2026-07 变更说明】本接口数据源已升级，响应结构全面更新（新增全部社媒指标、指标时序、扩展指标与带货数据），请按最新响应字段说明接入。","operationId":"chuhaijiang-social-video-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"platform_account_id":{"description":"平台账号 ID，与 platform_video_id 配合使用","type":"integer"},"platform_video_id":{"description":"平台视频 ID，来自「发布记录列表」返回的 platform_video_id。需与 platform_account_id 配合使用，用于定位从平台同步的帖子","type":"string"},"publication_id":{"description":"发布任务 ID，来自「发布记录列表」返回的 publication_id。与 platform_video_id 二选一，两者都传时优先使用本字段","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"description":"发布记录完整详情。optional 字段无数据时不返回","properties":{"account_avatar_url":{"description":"账号头像 URL（临时签名链接）","type":"string"},"account_display_name":{"description":"账号展示名","type":"string"},"account_username":{"description":"账号平台用户名，可能为空","type":"string"},"anchor_display_rate":{"description":"平均锚点展示率，0-1（仅 tiktok-shop-pc）","type":"number"},"click_through_rate":{"description":"平均点击率，0-1（仅 tiktok-shop-pc）","type":"number"},"comment_count":{"description":"累计评论数（仅 published 返回）","type":"integer"},"content_type":{"description":"内容类型：video（视频）/ image（图文）","type":"string"},"cover_url":{"description":"封面图 URL（临时签名链接）","type":"string"},"description":{"description":"帖子描述","type":"string"},"display_time":{"description":"展示时间戳（Unix 秒）：排期任务为计划发布时间，其余为创建/发布时间","type":"integer"},"engagement_rate":{"description":"互动率百分比 =（点赞+评论+分享）/播放×100。播放为 0 时不返回","type":"number"},"error_message":{"description":"发布失败原因（仅 failed 状态返回，已本地化）","type":"string"},"extra_metrics":{"description":"平台特有扩展指标（JSON 字符串，按 platform 解析，未采集到时不返回）。TikTok 含 19 项：completion_rate（完播率 0-1）、average_time_watched（平均观看秒数）、total_time_watched、reach（触达人数）、new_followers（视频带来的新增粉丝）、impression_sources（流量来源占比）、audience_types / audience_countries / audience_genders / audience_cities（受众分布）、video_view_retention（逐秒留存曲线）、engagement_likes（逐秒点赞分布）、profile_views、phone_number_clicks、lead_submissions、app_download_clicks、email_clicks、website_clicks、address_clicks。Instagram 含：reach（触达）、avg_watch_time / total_watch_time（Reels 观看时长，秒）","type":"string"},"favorite_count":{"description":"累计收藏数（仅 TikTok / Instagram 返回）","type":"integer"},"gmv":{"description":"累计销售额（仅 published 且 tiktok-shop-pc 返回）","type":"number"},"gmv_currency":{"description":"销售额币种","type":"string"},"last_refreshed_at":{"description":"指标最后刷新时间戳（Unix 秒）。可配合「刷新发布记录指标」接口主动刷新","type":"integer"},"like_count":{"description":"累计点赞数（仅 published 返回）","type":"integer"},"media_items":{"description":"多图列表（仅图文帖返回）（点击展开查看详细字段）","items":{"properties":{"order":{"description":"图片顺序，从 0 开始","type":"integer"},"presigned_url":{"description":"图片下载 URL（临时签名链接）","type":"string"}},"type":"object"},"type":"array"},"metric_series":{"description":"最近 30 天日级指标时序，值为当天的累计值（点击展开查看详细字段）","items":{"properties":{"comment_count":{"description":"当天累计评论","type":"integer"},"date":{"description":"日期，格式 YYYY-MM-DD","type":"string"},"favorite_count":{"description":"当天累计收藏（仅 TikTok / Instagram）","type":"integer"},"like_count":{"description":"当天累计点赞","type":"integer"},"share_count":{"description":"当天累计分享","type":"integer"},"view_count":{"description":"当天累计播放","type":"integer"}},"type":"object"},"type":"array"},"platform":{"description":"平台标识：tiktok / tiktok-shop-pc / instagram / youtube / facebook","type":"string"},"platform_account_id":{"description":"平台账号 ID","type":"integer"},"platform_url":{"description":"帖子在平台上的原始链接","type":"string"},"platform_video_id":{"description":"平台视频 ID","type":"string"},"products":{"description":"帖子关联的挂车商品（仅 tiktok-shop-pc）（点击展开查看详细字段）","items":{"properties":{"image_url":{"description":"商品主图 URL（临时签名链接）","type":"string"},"price_amount":{"description":"商品价格","type":"number"},"price_currency":{"description":"价格币种，默认 USD","type":"string"},"product_id":{"description":"TikTok Shop 商品 ID","type":"string"},"title":{"description":"商品标题","type":"string"}},"type":"object"},"type":"array"},"publication_id":{"description":"发布任务 ID。从平台同步（非本平台发布）的帖子为 0","type":"integer"},"published_at":{"description":"实际发布时间戳（Unix 秒）","type":"integer"},"region":{"description":"账号所属地区","type":"string"},"share_count":{"description":"累计分享数（仅 published 返回）","type":"integer"},"shop_daily_metrics":{"description":"最近 30 天日级带货时序（仅 tiktok-shop-pc）（点击展开查看详细字段）","items":{"properties":{"anchor_display_rate":{"description":"当天锚点（购物车）展示率，0-1","type":"number"},"click_through_rate":{"description":"当天点击率，0-1","type":"number"},"date":{"description":"日期，格式 YYYY-MM-DD","type":"string"},"gmv":{"description":"当天销售额","type":"number"},"gmv_currency":{"description":"币种","type":"string"},"items_sold":{"description":"当天售出件数","type":"integer"},"orders":{"description":"当天订单数","type":"integer"}},"type":"object"},"type":"array"},"status":{"description":"发布状态：published（已发布）/ scheduled（已排期）/ draft（草稿）/ failed（失败）/ cancelled（已取消）","type":"string"},"title":{"description":"帖子标题","type":"string"},"total_items_sold":{"description":"累计售出件数（仅 tiktok-shop-pc）","type":"integer"},"total_orders":{"description":"累计订单数（仅 tiktok-shop-pc）","type":"integer"},"video_url":{"description":"视频源文件下载 URL（临时签名链接，仅本平台发布的帖子返回，平台同步的帖子无此字段）","type":"string"},"view_count":{"description":"累计播放数（仅 published 返回）","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"发布记录详情","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/videos/export":{"post":{"description":"将已发布的社媒视频数据导出为 Excel 文件，返回下载链接（24h 有效）。单次最多导出 1000 条记录。","operationId":"chuhaijiang-social-videos-export","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"内容类型筛选。可选值：video / image","type":"string"},"end_time":{"description":"发布时间截止筛选（Unix 时间戳，秒）","type":"integer"},"limit":{"default":1000,"description":"导出条数，默认 1000，最大 1000","maximum":1000,"minimum":1,"type":"integer"},"offset":{"default":0,"description":"跳过前 N 条（0-based），用于分批导出","minimum":0,"type":"integer"},"platform":{"description":"平台筛选。可选值：tiktok / instagram / youtube / facebook","type":"string"},"platform_account_ids":{"description":"按账号 ID 列表筛选","items":{"type":"integer"},"type":"array"},"search":{"description":"模糊搜索视频标题","type":"string"},"sort_by":{"description":"排序字段。可选值：display_time（默认）/ views / likes / comments / shares / favorites / engagement / gmv / orders","type":"string"},"sort_order":{"description":"排序方向。可选值：desc（默认）/ asc","type":"string"},"start_time":{"description":"发布时间起始筛选（Unix 时间戳，秒）","type":"integer"},"timezone":{"description":"IANA 时区（如 America/Los_Angeles），用于格式化导出文件中的时间。不传则使用 UTC","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":10}},"schema":{"properties":{"data":{"properties":{"download_url":{"description":"Excel 文件下载链接（S3 预签名 URL，约 24 小时有效）","type":"string"},"exported_count":{"description":"实际导出行数（≤ 1000）","type":"integer"},"filename":{"description":"推荐的文件名","type":"string"},"total":{"description":"符合条件的总记录数（未截断的真实数量）","type":"integer"},"truncated":{"description":"是否被截断。true 表示总数超过 1000，仅导出了前 1000 条","type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"导出发布记录","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":10,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/videos/platform":{"post":{"description":"获取平台已发布视频列表及指标","operationId":"chuhaijiang-social-platform-videos","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"filter":{"description":"筛选条件","properties":{"published_after":{"description":"发布时间起始筛选（Unix 时间戳，秒）","type":"integer"},"published_before":{"description":"发布时间截止筛选（Unix 时间戳，秒）","type":"integer"},"search_keyword":{"description":"搜索关键词，匹配视频标题","type":"string"},"sort_by":{"description":"排序字段。可选值：published_at（发布时间，默认）/ play_count / like_count / comment_count / share_count","type":"string"},"sort_order":{"description":"排序方向。可选值：desc（降序，默认）/ asc（升序）","type":"string"}},"type":"object"},"filter_unread":{"description":"按未读评论筛选。true = 仅返回有未读评论的视频，false = 仅返回无未读评论的视频，不传 = 不筛选","type":"boolean"},"include_presigned_urls":{"description":"是否返回视频文件的预签名下载 URL。默认 false","type":"boolean"},"limit":{"default":20,"description":"每页条数，默认 20","maximum":100,"type":"integer"},"page":{"default":1,"description":"页码，从 1 开始","minimum":1,"type":"integer"},"platform_account_id":{"description":"账号 ID","type":"integer"},"platform_video_ids":{"description":"按平台侧视频 ID 精确筛选，传入视频 ID 列表","items":{"type":"string"},"type":"array"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"last_synced_at":{"description":"该账号视频数据最后同步时间（Unix 时间戳，秒）","type":"integer"},"limit":{"description":"每页条数","type":"integer"},"page":{"description":"当前页码","type":"integer"},"total_count":{"description":"符合条件的视频总数","type":"integer"},"videos":{"items":{"properties":{"cover_url":{"description":"封面图 URL","type":"string"},"duration":{"description":"视频时长（秒）","type":"number"},"media_type":{"description":"媒体类型：video / image / carousel","type":"string"},"metrics":{"description":"视频数据指标","properties":{"comment_count":{"description":"评论数","type":"integer"},"like_count":{"description":"点赞数","type":"integer"},"play_count":{"description":"播放量","type":"integer"},"share_count":{"description":"分享数","type":"integer"}},"type":"object"},"metrics_updated_at":{"description":"指标最后更新时间（Unix 时间戳，秒）","type":"integer"},"platform":{"description":"平台标识","type":"string"},"platform_url":{"description":"视频在平台上的 URL","type":"string"},"platform_video_id":{"description":"平台侧视频 ID","type":"string"},"publication_id":{"description":"关联的发布任务 ID（通过本系统发布时返回，第三方发布为 null）","type":"integer"},"published_at":{"description":"发布时间（Unix 时间戳，秒）","type":"integer"},"video_id":{"description":"视频记录 ID（系统内部标识）","type":"integer"},"video_title":{"description":"视频标题","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频数据列表","tags":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/tasks/{task_id}":{"get":{"description":"查询异步任务的执行状态和结果。任务失败时 Gateway 自动退款，status 变为 refunded。","operationId":"task-status","parameters":[{"description":"异步任务 ID（由异步接口返回）","in":"path","name":"task_id","required":true,"schema":{"type":"string"}},{"description":"Your API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"status":"completed","task_id":"task_abc123"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"error_message":{"description":"失败原因（仅 refunded 状态）","type":"string"},"result":{"description":"任务结果（仅 completed 状态）","type":"object"},"status":{"description":"任务状态","enum":["pending","running","completed","refunded"],"type":"string"},"task_id":{"description":"任务 ID","type":"string"}},"required":["task_id","status"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询异步任务状态","tags":["异步任务"],"x-billing-mode":"free","x-coin-cost":0}},"/open/v1/upload/presigned-url":{"post":{"description":"生成 TOS 加速预签名上传 URL，用于客户端直传文件。使用流程：1. 调用本接口获取 presigned URL；2. 使用返回的 url 字段通过 HTTP PUT 上传文件；3. 上传完成后 signed_url 即可访问文件。\n\n适用场景：\n- AI 生成接口：上传后的 signed_url 可直接作为 AI 视频/图片生成接口（如 SeeDance2.0 Pro）的参考图片（images[].url）、参考视频（reference_videos[].url）等参数传入\n- 社媒发布：上传后返回的 os_bucket 和 os_key 可作为社媒发布接口的 bucket_name 和 bucket_key 参数传入\n\nsigned_url 有效期 24 小时，上传 URL 有效期 180 秒。","operationId":"chuhaijiang-upload-presigned-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"file_name":{"description":"文件名（含扩展名），如 video.mp4 或 cover.jpg","type":"string"}},"required":["file_name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"os_bucket":{"description":"存储桶名称。调用发布接口时传入 bucket_name 字段","type":"string"},"os_key":{"description":"对象存储路径。调用发布接口时传入 bucket_key 字段","type":"string"},"signed_url":{"description":"上传完成后的文件访问 URL（GET 方法，24小时有效）","type":"string"},"url":{"description":"预签名上传 URL。使用 HTTP PUT 方法上传文件到此 URL，有效期 180 秒，走 TOS 加速端点","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"（加速版）生成上传预签名URL","tags":["文件上传"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.upload.write"}},"/open/v1/video-editor/capabilities":{"get":{"description":"查询当前部署支持的编辑操作、异步动作和参数范围。","operationId":"chuhaijiang-video-editor-capabilities","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑器能力响应","properties":{"actions":{"description":"支持的异步动作；各动作参数见“提交视频编辑异步动作”","items":{"description":"动作类型","enum":["auto_captions","detach_video_audio","generate_voiceover"],"type":"string"},"type":"array"},"assets":{"description":"可插入素材能力（点击展开查看详细字段）","properties":{"accepted_origins":{"description":"允许的素材来源","items":{"description":"素材来源","enum":["asset_library","user_upload","ai_generated","system_music"],"type":"string"},"type":"array"},"insertable_kinds":{"description":"允许插入的素材类型","items":{"description":"素材类型","enum":["video","image","audio","bgm"],"type":"string"},"type":"array"}},"type":"object"},"audio":{"description":"音频能力（点击展开查看详细字段）","properties":{"project_source_audio_volume":{"description":"项目源音频音量范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"segment_volume":{"description":"片段音量范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"}},"type":"object"},"cache_ttl_seconds":{"description":"能力信息缓存时间，单位秒","type":"integer"},"composition":{"description":"直接视频合成能力（点击展开查看详细字段）","properties":{"aspect_ratios":{"description":"支持的画幅比例","items":{"description":"画幅比例","type":"string"},"type":"array"},"max_segments":{"description":"单次合成最大视频片段数","type":"integer"}},"type":"object"},"contract_revision":{"description":"当前契约修订号；写请求必须原样回传","type":"string"},"max_operations_per_mutation":{"description":"单次编辑请求允许的最大操作数","type":"integer"},"operations":{"description":"支持的同步编辑操作；各操作参数见“预演视频编辑修改”或“应用视频编辑修改”","items":{"description":"操作类型","enum":["move_segment","resize_segment","trim_segment","split_segment","delete_segment","set_transition","remove_transition","update_transition_duration","set_segment_volume","set_project_source_audio","restore_video_audio","upsert_subtitle","delete_subtitle","update_subtitle_style","insert_asset_segment","replace_segment_asset","update_segment_transform","set_segment_speed","upsert_text","insert_sticker","update_project"],"type":"string"},"type":"array"},"realtime":{"description":"实时同步能力（点击展开查看详细字段）","properties":{"event_type":{"description":"事件类型","type":"string"},"mode":{"description":"同步模式","type":"string"},"schema_version":{"description":"事件 schema 版本","type":"integer"}},"type":"object"},"render":{"description":"渲染能力（点击展开查看详细字段）","properties":{"draft_max_width":{"description":"草稿渲染最大宽度范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"modes":{"description":"支持的渲染模式","items":{"description":"渲染模式","type":"string"},"type":"array"},"qualities":{"description":"支持的渲染质量","items":{"description":"渲染质量","type":"string"},"type":"array"}},"type":"object"},"speed":{"description":"变速能力（点击展开查看详细字段）","properties":{"media":{"description":"媒体播放速度范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"preserve_pitch":{"description":"是否支持保持音高","type":"boolean"}},"type":"object"},"sticker":{"description":"贴纸能力（点击展开查看详细字段）","properties":{"catalog_revision":{"description":"贴纸目录版本","type":"string"},"default_duration_us":{"description":"默认持续时间，单位微秒","type":"integer"}},"type":"object"},"still_image":{"description":"静态图片默认行为（点击展开查看详细字段）","properties":{"default_duration_us":{"description":"默认持续时间，单位微秒","type":"integer"}},"type":"object"},"subtitle":{"description":"字幕能力（点击展开查看详细字段）","properties":{"default_style":{"description":"默认字幕样式","type":"string"},"max_segments_per_style_operation":{"description":"单次样式操作最多处理的字幕数","type":"integer"},"max_text_length":{"description":"最大字幕文本长度","type":"integer"},"styles":{"description":"支持的字幕样式","items":{"description":"样式名称","type":"string"},"type":"array"}},"type":"object"},"text":{"description":"文本能力（点击展开查看详细字段）","properties":{"font_families":{"description":"可用字体","items":{"description":"字体名称","type":"string"},"type":"array"},"font_size":{"description":"字号范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"font_styles":{"description":"可用字体样式","items":{"description":"样式","type":"string"},"type":"array"},"font_weights":{"description":"可用字重","items":{"description":"字重","type":"string"},"type":"array"},"max_length":{"description":"最大文本长度","type":"integer"},"minimum_visible_width_px":{"description":"最小可见宽度，像素","type":"integer"},"opacity":{"description":"不透明度范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"presets":{"description":"可用文字预设","items":{"description":"预设名称","type":"string"},"type":"array"},"scale":{"description":"文本缩放范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"text_alignments":{"description":"可用对齐方式","items":{"description":"对齐方式","type":"string"},"type":"array"},"text_decorations":{"description":"可用文本装饰","items":{"description":"装饰","type":"string"},"type":"array"}},"type":"object"},"time_unit":{"description":"所有时间轴字段的单位","enum":["microsecond"],"type":"string"},"timeline":{"description":"时间线行为（点击展开查看详细字段）","properties":{"automatic_empty_track_cleanup":{"description":"是否自动清理空轨道","type":"boolean"},"implicit_track_creation":{"description":"是否允许按需自动创建轨道","type":"boolean"},"main_video_track_code":{"description":"主视频轨道显示编号","type":"string"}},"type":"object"},"transform":{"description":"画面变换限制（点击展开查看详细字段）","properties":{"aspect_ratio_tolerance":{"description":"宽高比容差","type":"number"},"coordinate_space":{"description":"坐标系","enum":["composition_pixel"],"type":"string"},"minimum_object_size_px":{"description":"对象最小尺寸，像素","type":"integer"},"minimum_visible_size_px":{"description":"最小可见尺寸，像素","type":"integer"},"rotation_degree":{"description":"旋转角度范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max_exclusive":{"description":"不包含的最大值","type":"number"},"min_inclusive":{"description":"包含的最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"scale_percent":{"description":"缩放百分比范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"}},"type":"object"},"transition":{"description":"转场能力（点击展开查看详细字段）","properties":{"duration_us":{"description":"转场时长范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"types":{"description":"支持的转场类型","items":{"description":"转场类型","enum":["blend","slide_left","slide_right","slide_up","slide_down","white_flash","black_flash"],"type":"string"},"type":"array"}},"type":"object"},"voiceover":{"description":"旁白能力（点击展开查看详细字段）","properties":{"language_codes":{"description":"支持的语言代码","items":{"description":"语言代码","type":"string"},"type":"array"},"source_types":{"description":"支持的音色来源","items":{"description":"音色来源","enum":["system_voice","voice_profile"],"type":"string"},"type":"array"},"system_voice_speaking_rate":{"description":"系统音色语速范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"},"system_voices":{"description":"系统音色","items":{"description":"系统音色（点击展开查看详细字段）","properties":{"display_name":{"description":"显示名称","type":"string"},"voice_id":{"description":"音色 ID","type":"string"}},"type":"object"},"type":"array"},"voice_profile_speaking_rate":{"description":"用户音色语速范围（点击展开查看详细字段）","properties":{"default":{"description":"默认值","type":"number"},"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"},"step":{"description":"步长","type":"number"}},"type":"object"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询视频编辑器能力","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"}},"/open/v1/video-editor/compositions":{"post":{"description":"不创建项目，按片段顺序直接合成视频。","operationId":"chuhaijiang-video-editor-compositions-create","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"提交直接视频合成的请求","properties":{"aspect_ratio":{"description":"成片比例：9:16、16:9 或 1:1","enum":["9:16","16:9","1:1"],"type":"string"},"client_request_id":{"description":"调用方幂等 ID","type":"string"},"language":{"description":"内容语言","type":"string"},"preserve_source_audio":{"description":"是否保留原片段声音；默认 true","type":"boolean"},"segments":{"description":"按顺序合成的视频片段，最多 100 段","items":{"description":"直接合成的视频片段；视频来源必须在素材库 ID 与对象存储坐标中二选一（点击展开查看详细字段）","properties":{"display_name":{"description":"人类可读片段名","type":"string"},"duration_us":{"description":"期望使用时长，单位微秒","type":"integer"},"id":{"description":"调用方片段 ID","type":"string"},"thumbnail_os_bucket":{"description":"缩略图 Bucket","type":"string"},"thumbnail_os_key":{"description":"缩略图 Key","type":"string"},"video_asset_id":{"description":"用户素材库 collection item ID，必须为十进制数字字符串","type":"string"},"video_os_bucket":{"description":"对象存储 Bucket","type":"string"},"video_os_key":{"description":"对象存储 Key","type":"string"}},"type":"object"},"maxItems":100,"minItems":1,"type":"array"},"session_id":{"description":"业务会话 ID，用于归档与追踪","type":"string"},"title":{"description":"成片标题","type":"string"}},"required":["client_request_id","session_id","segments"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"直接视频合成提交响应","properties":{"assembly_mode":{"description":"下游选择的合成模式","type":"string"},"client_request_id":{"description":"调用方幂等 ID","type":"string"},"duration_us":{"description":"预计或实际总时长，单位微秒","type":"integer"},"preserve_source_audio":{"description":"实际采用的原声策略","type":"boolean"},"reused":{"description":"是否复用了已有任务","type":"boolean"},"status":{"description":"当前任务状态","type":"string"},"task_id":{"description":"合成任务 ID","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"202":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"直接视频合成提交响应","properties":{"assembly_mode":{"description":"下游选择的合成模式","type":"string"},"client_request_id":{"description":"调用方幂等 ID","type":"string"},"duration_us":{"description":"预计或实际总时长，单位微秒","type":"integer"},"preserve_source_audio":{"description":"实际采用的原声策略","type":"boolean"},"reused":{"description":"是否复用了已有任务","type":"boolean"},"status":{"description":"当前任务状态","type":"string"},"task_id":{"description":"合成任务 ID","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Accepted: asynchronous processing is in progress"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"提交直接视频合成","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/compositions/{task_id}":{"get":{"description":"查询直接视频合成进度、产物对象地址和失败信息。","operationId":"chuhaijiang-video-editor-compositions-get","parameters":[{"description":"合成任务 ID","in":"path","name":"task_id","required":true,"schema":{"type":"string"}},{"description":"成功时是否返回临时下载地址","in":"query","name":"presign","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"直接视频合成状态响应","properties":{"download_url":{"description":"presign=true 且产物可用时的临时下载地址","type":"string"},"duration_us":{"description":"成片时长，单位微秒","type":"integer"},"error_message":{"description":"失败详情","type":"string"},"progress":{"description":"任务进度","type":"number"},"status":{"description":"当前任务状态","type":"string"},"task_id":{"description":"合成任务 ID","type":"string"},"title":{"description":"成片标题","type":"string"},"video_os_bucket":{"description":"成片对象存储 Bucket","type":"string"},"video_os_key":{"description":"成片对象存储 Key","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询直接视频合成","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"}},"/open/v1/video-editor/projects":{"get":{"description":"分页查询当前用户可编辑的 ShotPlan 项目。","operationId":"chuhaijiang-video-editor-projects-list","parameters":[{"description":"上一页响应的 next_cursor；首页不传","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"每页返回数量；以服务端上限为准","in":"query","name":"limit","required":false,"schema":{"minimum":1,"type":"integer"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑项目列表响应","properties":{"has_more":{"description":"是否还有更多项目","type":"boolean"},"next_cursor":{"description":"下一页不透明游标","type":"string"},"projects":{"description":"当前用户可编辑的项目摘要列表","items":{"description":"项目摘要（点击展开查看详细字段）","properties":{"edit_version":{"description":"项目编辑版本","type":"integer"},"project_id":{"description":"项目 ID","type":"string"},"title":{"description":"项目标题","type":"string"},"updated_at":{"description":"更新时间，RFC3339","type":"string"},"version":{"description":"项目内容版本","type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询视频编辑项目列表","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"},"post":{"description":"使用视频素材创建一个可编辑的视频项目，可选附加背景音频。建议直接传入画布或素材库返回的稳定对象存储坐标；成功后使用项目上下文、预演编辑、应用编辑和项目渲染接口继续处理。每次调用都会创建一个新项目，请复用返回的 project_id，避免因重试重复创建。","operationId":"chuhaijiang-video-editor-projects-create","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"创建视频编辑项目请求（点击展开查看详细字段）","properties":{"aspect_ratio":{"description":"项目画幅比；留空时使用第一个视频的画幅比，仍未提供时默认为 9:16","type":"string"},"audios":{"description":"可选的背景音乐素材，按数组顺序拼接","items":{"description":"按顺序放入背景音乐轨道的音频素材（点击展开查看详细字段）","properties":{"audio_os_bucket":{"description":"音频的稳定对象存储 Bucket，使用画布或素材库返回的坐标","type":"string"},"audio_os_key":{"description":"音频的稳定对象存储 Key，使用画布或素材库返回的坐标","type":"string"},"duration_s":{"description":"音频时长，单位秒","minimum":0.001,"type":"number"},"id":{"description":"调用方对该音频素材的可选唯一标识","type":"string"},"name":{"description":"音频素材名称","type":"string"}},"required":["audio_os_bucket","audio_os_key","duration_s"],"type":"object"},"type":"array"},"session_id":{"description":"客户端生成的会话 ID；建议使用 UUID，并在本次创建请求中保持唯一","type":"string"},"title":{"description":"项目标题；留空时由服务端使用默认标题","type":"string"},"videos":{"description":"按顺序创建视频轨道的视频素材","items":{"description":"待放入时间轴的视频素材（点击展开查看详细字段）","properties":{"aspect_ratio":{"description":"视频画幅比，例如 9:16、16:9 或 1:1","type":"string"},"duration_s":{"description":"视频时长，单位秒，用于准确创建时间轴","minimum":0.001,"type":"number"},"id":{"description":"调用方对该视频素材的可选唯一标识","type":"string"},"name":{"description":"视频素材名称","type":"string"},"thumbnail_os_bucket":{"description":"可选的视频缩略图稳定对象存储 Bucket","type":"string"},"thumbnail_os_key":{"description":"可选的视频缩略图稳定对象存储 Key","type":"string"},"video_os_bucket":{"description":"视频的稳定对象存储 Bucket，使用画布或素材库返回的坐标","type":"string"},"video_os_key":{"description":"视频的稳定对象存储 Key，使用画布或素材库返回的坐标","type":"string"}},"required":["video_os_bucket","video_os_key","duration_s"],"type":"object"},"minItems":1,"type":"array"}},"required":["session_id","videos"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"创建视频编辑项目响应","properties":{"project":{"description":"新建的视频编辑项目摘要（点击展开查看详细字段）","properties":{"edit_version":{"description":"项目编辑版本；提交编辑和渲染时按对应接口要求传入","type":"integer"},"project_id":{"description":"新建项目 ID；用于后续查询、编辑和渲染接口的 project_id 路径参数","type":"string"},"title":{"description":"项目标题","type":"string"},"version":{"description":"项目数据版本","type":"integer"}},"required":["project_id","title","version","edit_version"],"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"创建视频编辑项目","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/actions":{"post":{"description":"提交自动字幕、视频声音分离或旁白生成任务。","operationId":"chuhaijiang-video-editor-actions-submit","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"提交异步编辑动作的请求","properties":{"action":{"description":"动作类型：auto_captions、detach_video_audio 或 generate_voiceover","enum":["auto_captions","detach_video_audio","generate_voiceover"],"type":"string"},"client_mutation_id":{"description":"调用方幂等 ID","type":"string"},"expected_edit_version":{"description":"项目编辑版本","type":"integer"},"expected_version":{"description":"项目内容版本","type":"integer"},"parameters":{"description":"异步动作参数；具体字段取决于 action（点击展开查看详细字段）","properties":{"clear_existing_subtitles":{"description":"auto_captions 是否先清除既有字幕","type":"boolean"},"language_code":{"description":"auto_captions 的转写语言代码","type":"string"},"placement":{"description":"旁白在线上的放置策略（点击展开查看详细字段）","properties":{"collision_policy":{"description":"碰撞策略：reject、slot 或 push_forward","type":"string"},"link_subtitles":{"description":"字幕来源时是否保留字幕关联","type":"boolean"},"replace_segment_id":{"description":"替换的已有旁白片段 ID","type":"string"},"start_us":{"description":"旁白时间线起点，单位微秒","type":"integer"},"target_track":{"description":"目标轨道；existing 使用已有轨道，new 自动创建轨道（点击展开查看详细字段）","properties":{"insert_after_track_id":{"description":"新轨道插入位置；省略则按服务端规则放置","type":"string"},"kind":{"description":"new 模式下的新轨道类型：video、sticker、subtitle、voiceover 或 bgm","type":"string"},"mode":{"description":"轨道选择模式：existing 或 new","enum":["existing","new"],"type":"string"},"track_id":{"description":"existing 模式下的稳定轨道 ID","type":"string"}},"required":["mode"],"type":"object"},"volume":{"description":"旁白音量，范围 0..2","type":"number"}},"required":["start_us"],"type":"object"},"source":{"description":"旁白文字来源；type 与对应负载字段必须一一匹配（点击展开查看详细字段）","properties":{"scene_id":{"description":"分镜场景 ID","type":"string"},"subtitle_segment_ids":{"description":"按时间顺序拼接的字幕片段 ID","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"text":{"description":"直接生成旁白的文本，长度 1..5000","type":"string"},"type":{"description":"来源类型：text、subtitle_segments、scene_script 或 voiceover_segment","enum":["text","subtitle_segments","scene_script","voiceover_segment"],"type":"string"},"voiceover_segment_id":{"description":"已有旁白片段 ID","type":"string"}},"required":["type"],"type":"object"},"video_segment_id":{"description":"detach_video_audio 的视频片段 ID","type":"string"},"voice":{"description":"旁白音色与语速设置（点击展开查看详细字段）","properties":{"instructions":{"description":"发音或情绪提示，最多 1000 字符","type":"string"},"language_code":{"description":"语言代码，必须为 capabilities 支持的值","type":"string"},"source_type":{"description":"音色来源：system_voice 或 voice_profile","enum":["system_voice","voice_profile"],"type":"string"},"speaking_rate":{"description":"语速；系统音色范围 0.25..4，用户音色范围 0.5..2","type":"number"},"voice_id":{"description":"系统音色 ID；system_voice 时必填","type":"string"},"voice_profile_id":{"description":"当前用户音色 ID；voice_profile 时必填","type":"string"}},"required":["source_type","language_code"],"type":"object"}},"type":"object"},"source_client_id":{"description":"调用方实例 ID","type":"string"}},"required":["action","expected_version","expected_edit_version","client_mutation_id","parameters"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"异步编辑动作提交响应；字段因 action 而异","properties":{"action":{"description":"动作类型","enum":["auto_captions","detach_video_audio","generate_voiceover"],"type":"string"},"base_edit_version":{"description":"提交时项目编辑版本；generate_voiceover 返回","type":"integer"},"base_version":{"description":"提交时项目内容版本；generate_voiceover 返回","type":"integer"},"completed_at":{"description":"任务完成时间，RFC3339","format":"date-time","type":"string"},"created_at":{"description":"任务创建时间，RFC3339","format":"date-time","type":"string"},"error_code":{"description":"失败代码","type":"string"},"error_message":{"description":"失败说明","type":"string"},"job_id":{"description":"异步任务 ID","type":"string"},"mutation_id":{"description":"已完成时的修改 ID","type":"string"},"project_id":{"description":"项目 ID","type":"string"},"result":{"description":"生成旁白完成结果（点击展开查看详细字段）","properties":{"applied_edit_version":{"description":"应用后的项目编辑版本","type":"integer"},"applied_version":{"description":"应用后的项目内容版本","type":"integer"},"audio_asset_id":{"description":"生成的音频素材 ID","type":"string"},"duration_us":{"description":"旁白时长，单位微秒","type":"integer"},"linked_subtitle_segment_ids":{"description":"关联的字幕片段 ID","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"material_id":{"description":"项目素材 ID","type":"string"},"mutation_id":{"description":"产生的修改 ID","type":"string"},"segment_id":{"description":"新建旁白片段 ID","type":"string"},"track_display_code":{"description":"旁白轨道显示编号","type":"string"},"track_id":{"description":"旁白轨道 ID","type":"string"}},"type":"object"},"reused":{"description":"是否复用幂等任务","type":"boolean"},"status":{"description":"任务状态","type":"string"},"updated_at":{"description":"任务更新时间，RFC3339","format":"date-time","type":"string"}},"required":["action","job_id","project_id","status","reused","created_at"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"202":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"异步编辑动作提交响应；字段因 action 而异","properties":{"action":{"description":"动作类型","enum":["auto_captions","detach_video_audio","generate_voiceover"],"type":"string"},"base_edit_version":{"description":"提交时项目编辑版本；generate_voiceover 返回","type":"integer"},"base_version":{"description":"提交时项目内容版本；generate_voiceover 返回","type":"integer"},"completed_at":{"description":"任务完成时间，RFC3339","format":"date-time","type":"string"},"created_at":{"description":"任务创建时间，RFC3339","format":"date-time","type":"string"},"error_code":{"description":"失败代码","type":"string"},"error_message":{"description":"失败说明","type":"string"},"job_id":{"description":"异步任务 ID","type":"string"},"mutation_id":{"description":"已完成时的修改 ID","type":"string"},"project_id":{"description":"项目 ID","type":"string"},"result":{"description":"生成旁白完成结果（点击展开查看详细字段）","properties":{"applied_edit_version":{"description":"应用后的项目编辑版本","type":"integer"},"applied_version":{"description":"应用后的项目内容版本","type":"integer"},"audio_asset_id":{"description":"生成的音频素材 ID","type":"string"},"duration_us":{"description":"旁白时长，单位微秒","type":"integer"},"linked_subtitle_segment_ids":{"description":"关联的字幕片段 ID","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"material_id":{"description":"项目素材 ID","type":"string"},"mutation_id":{"description":"产生的修改 ID","type":"string"},"segment_id":{"description":"新建旁白片段 ID","type":"string"},"track_display_code":{"description":"旁白轨道显示编号","type":"string"},"track_id":{"description":"旁白轨道 ID","type":"string"}},"type":"object"},"reused":{"description":"是否复用幂等任务","type":"boolean"},"status":{"description":"任务状态","type":"string"},"updated_at":{"description":"任务更新时间，RFC3339","format":"date-time","type":"string"}},"required":["action","job_id","project_id","status","reused","created_at"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Accepted: asynchronous processing is in progress"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"提交视频编辑异步动作","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/actions/{job_id}":{"get":{"description":"查询自动字幕、分离声音或旁白生成任务的状态和结果。","operationId":"chuhaijiang-video-editor-action-get","parameters":[{"description":"项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"提交动作时返回的任务 ID","in":"path","name":"job_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"异步编辑动作查询响应；字段因 action 而异","properties":{"action":{"description":"动作类型","enum":["auto_captions","detach_video_audio","generate_voiceover"],"type":"string"},"applied_edit_version":{"description":"应用后的项目编辑版本","type":"integer"},"applied_version":{"description":"应用后的项目内容版本","type":"integer"},"base_edit_version":{"description":"提交时项目编辑版本","type":"integer"},"base_version":{"description":"提交时项目内容版本","type":"integer"},"completed_at":{"description":"任务完成时间，RFC3339","format":"date-time","type":"string"},"created_at":{"description":"任务创建时间，RFC3339","format":"date-time","type":"string"},"created_subtitle_count":{"description":"自动字幕成功创建的字幕数量","type":"integer"},"error_code":{"description":"失败代码","type":"string"},"error_message":{"description":"失败说明","type":"string"},"job_id":{"description":"异步任务 ID","type":"string"},"mutation_id":{"description":"已完成时的修改 ID","type":"string"},"project_id":{"description":"项目 ID","type":"string"},"result":{"description":"生成旁白完成结果（点击展开查看详细字段）","properties":{"applied_edit_version":{"description":"应用后的项目编辑版本","type":"integer"},"applied_version":{"description":"应用后的项目内容版本","type":"integer"},"audio_asset_id":{"description":"生成的音频素材 ID","type":"string"},"duration_us":{"description":"旁白时长，单位微秒","type":"integer"},"linked_subtitle_segment_ids":{"description":"关联的字幕片段 ID","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"material_id":{"description":"项目素材 ID","type":"string"},"mutation_id":{"description":"产生的修改 ID","type":"string"},"segment_id":{"description":"新建旁白片段 ID","type":"string"},"track_display_code":{"description":"旁白轨道显示编号","type":"string"},"track_id":{"description":"旁白轨道 ID","type":"string"}},"type":"object"},"reused":{"description":"是否复用幂等任务","type":"boolean"},"status":{"description":"任务状态","type":"string"},"updated_at":{"description":"任务更新时间，RFC3339","format":"date-time","type":"string"},"video_segment_id":{"description":"分离音频的源视频片段 ID","type":"string"}},"required":["action","job_id","project_id","status","created_at","updated_at"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询视频编辑异步动作","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"}},"/open/v1/video-editor/projects/{project_id}/context":{"get":{"description":"查询项目版本、轨道、片段、素材和关系。","operationId":"chuhaijiang-video-editor-project-context","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"可选的时间窗口起点","in":"query","name":"start_us","required":false,"schema":{"type":"integer"}},{"description":"可选的时间窗口终点","in":"query","name":"end_us","required":false,"schema":{"type":"integer"}},{"description":"仅返回指定轨道","in":"query","name":"track_ids","required":false,"schema":{"type":"string"}},{"description":"需要包含的上下文集合","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"片段分页游标","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"片段分页数量","in":"query","name":"limit","required":false,"schema":{"minimum":1,"type":"integer"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑项目上下文","properties":{"boundaries":{"description":"视频片段边界列表","items":{"description":"边界（点击展开查看详细字段）","properties":{"at_us":{"description":"边界时间，单位微秒","type":"integer"},"boundary_id":{"description":"边界 ID","type":"string"},"from_segment_id":{"description":"前一片段 ID","type":"string"},"to_segment_id":{"description":"后一片段 ID","type":"string"},"track_id":{"description":"轨道 ID","type":"string"},"transition":{"description":"边界转场（点击展开查看详细字段）","properties":{"duration_us":{"description":"转场时长，单位微秒","type":"integer"},"transition_id":{"description":"转场 ID","type":"string"},"transition_type":{"description":"转场类型","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"export":{"description":"导出状态（点击展开查看详细字段）","properties":{"has_unexported_edits":{"description":"是否有未导出修改","type":"boolean"},"latest_export_id":{"description":"最近导出任务 ID","type":"string"},"source_audio":{"additionalProperties":true,"description":"源音频导出状态；字段随项目导出策略变化","type":"object"}},"type":"object"},"has_more":{"description":"是否还有更多片段","type":"boolean"},"materials":{"description":"素材列表","items":{"description":"素材（点击展开查看详细字段）","properties":{"duration_us":{"description":"时长，单位微秒","type":"integer"},"kind":{"description":"素材类型","type":"string"},"material_id":{"description":"素材 ID","type":"string"},"name":{"description":"素材名称","type":"string"},"origin":{"description":"素材来源","type":"string"},"status":{"description":"素材状态","type":"string"}},"type":"object"},"type":"array"},"next_cursor":{"description":"下一页游标；无更多结果时为空","type":"string"},"project":{"description":"项目摘要（点击展开查看详细字段）","properties":{"composition":{"description":"画布信息（点击展开查看详细字段）","properties":{"canvas":{"description":"画布尺寸（点击展开查看详细字段）","properties":{"aspect_ratio":{"description":"画幅比例","type":"string"},"height":{"description":"高度","type":"number"},"width":{"description":"宽度","type":"number"}},"type":"object"},"fps":{"description":"帧率","type":"number"}},"type":"object"},"duration_us":{"description":"项目时长，单位微秒","type":"integer"},"edit_version":{"description":"项目编辑版本","type":"integer"},"has_unexported_edits":{"description":"是否有未导出的修改","type":"boolean"},"language_code":{"description":"项目语言代码","type":"string"},"latest_export_id":{"description":"最近导出任务 ID","type":"string"},"project_id":{"description":"项目 ID","type":"string"},"title":{"description":"项目标题","type":"string"},"updated_at":{"description":"最近更新时间，RFC3339","format":"date-time","type":"string"},"version":{"description":"项目内容版本","type":"integer"}},"required":["project_id","title","duration_us","version","edit_version","has_unexported_edits","updated_at","composition","language_code"],"type":"object"},"relationships":{"description":"已公开的片段关系","items":{"description":"视频与分离音频关系（点击展开查看详细字段）","properties":{"from_segment_id":{"description":"源视频片段 ID","type":"string"},"id":{"description":"关系 ID","type":"string"},"material_id":{"description":"音频素材 ID","type":"string"},"to_segment_id":{"description":"生成音频片段 ID","type":"string"},"type":{"description":"关系类型","enum":["video_detached_audio"],"type":"string"}},"type":"object"},"type":"array"},"segments":{"description":"片段列表","items":{"description":"片段（点击展开查看详细字段）","properties":{"kind":{"description":"片段类型","type":"string"},"label":{"description":"片段标签","type":"string"},"material_id":{"description":"素材 ID","type":"string"},"playback_rate":{"description":"播放速度","type":"number"},"preserve_pitch":{"description":"是否保持音高","type":"boolean"},"segment_id":{"description":"片段 ID","type":"string"},"source_range":{"description":"源媒体区间（点击展开查看详细字段）","properties":{"duration_us":{"description":"持续时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"sticker":{"description":"贴纸信息（点击展开查看详细字段）","properties":{"catalog_revision":{"description":"贴纸目录版本","type":"string"},"category":{"description":"贴纸分类","type":"string"},"effect_id":{"description":"贴纸效果 ID","type":"string"},"freeze":{"description":"是否冻结末帧","type":"boolean"},"intrinsic_height":{"description":"原始高度","type":"number"},"intrinsic_width":{"description":"原始宽度","type":"number"},"loop":{"description":"是否循环","type":"boolean"},"media_type":{"description":"媒体类型","type":"string"}},"type":"object"},"target_range":{"description":"时间线区间（点击展开查看详细字段）","properties":{"duration_us":{"description":"持续时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"text":{"description":"字幕文本与样式（点击展开查看详细字段）","properties":{"style":{"description":"文本样式（点击展开查看详细字段）","properties":{"background_color":{"description":"背景色","type":"string"},"color":{"description":"文字颜色","type":"string"},"font_family":{"description":"字体","type":"string"},"font_size":{"description":"字号","type":"number"},"font_style":{"description":"字体样式","type":"string"},"font_weight":{"description":"字重","type":"string"},"letter_spacing":{"description":"字间距","type":"number"},"line_height":{"description":"行高","type":"number"},"opacity":{"description":"不透明度","type":"number"},"preset":{"description":"文字预设","type":"string"},"scale":{"description":"缩放比例","type":"number"},"shadow_blur":{"description":"阴影模糊度","type":"number"},"shadow_color":{"description":"阴影颜色","type":"string"},"stroke_color":{"description":"描边颜色","type":"string"},"stroke_width":{"description":"描边宽度","type":"number"},"text_align":{"description":"对齐方式","type":"string"},"text_decoration":{"description":"文本装饰","type":"string"},"text_orientation":{"description":"文字方向","type":"string"},"text_transform":{"description":"文本转换","type":"string"},"writing_mode":{"description":"书写方向","type":"string"}},"type":"object"},"text":{"description":"字幕文本","type":"string"}},"type":"object"},"track_id":{"description":"所属轨道 ID","type":"string"},"transform":{"description":"画面变换参数（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"画布横坐标","type":"number"},"rotation_degree":{"description":"旋转角度","type":"number"},"top":{"description":"画布纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"type":"object"},"voice":{"additionalProperties":true,"description":"旁白配置；稳定字段由生成旁白动作的参数决定","type":"object"},"volume":{"description":"片段音量","type":"number"}},"type":"object"},"type":"array"},"subtitles":{"description":"字幕列表","items":{"description":"字幕（点击展开查看详细字段）","properties":{"duration_us":{"description":"持续时间，单位微秒","type":"integer"},"segment_id":{"description":"字幕片段 ID","type":"string"},"start_us":{"description":"开始时间，单位微秒","type":"integer"},"style":{"description":"字幕样式","type":"string"},"text":{"description":"字幕文本","type":"string"}},"type":"object"},"type":"array"},"tracks":{"description":"轨道列表","items":{"description":"轨道（点击展开查看详细字段）","properties":{"display_code":{"description":"稳定显示编号","type":"string"},"kind":{"description":"轨道类型","type":"string"},"locked":{"description":"是否锁定","type":"boolean"},"muted":{"description":"是否静音","type":"boolean"},"name":{"description":"轨道名称","type":"string"},"order":{"description":"轨道排序值","type":"number"},"role":{"description":"轨道角色","type":"string"},"segment_count":{"description":"片段数量","type":"integer"},"track_id":{"description":"轨道 ID","type":"string"},"visible":{"description":"是否可见","type":"boolean"}},"type":"object"},"type":"array"}},"required":["project","has_more"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询视频编辑项目上下文","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"}},"/open/v1/video-editor/projects/{project_id}/edits/apply":{"post":{"description":"原子应用已预演的一组同步编辑操作。","operationId":"chuhaijiang-video-editor-edits-apply","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"原子应用预演编辑的请求","properties":{"client_mutation_id":{"description":"调用方幂等 ID；重试时必须复用","type":"string"},"contract_revision":{"description":"契约修订号，必须等于 capabilities 返回值","type":"string"},"expected_edit_version":{"description":"项目编辑版本，必须等于当前版本","type":"integer"},"expected_version":{"description":"项目内容版本，必须等于当前版本","type":"integer"},"operations":{"description":"按顺序执行的同步编辑操作","items":{"description":"单条同步编辑操作；op 决定哪些字段生效，完整操作与参数范围以 capabilities 返回为准（点击展开查看详细字段）","properties":{"asset_id":{"description":"用户素材库素材 ID","type":"string"},"asset_kind":{"description":"素材类型：video、image、audio 或 bgm","type":"string"},"at_us":{"description":"切分或边界时间点，单位微秒","type":"integer"},"catalog_revision":{"description":"贴纸目录版本","type":"string"},"duration_policy":{"description":"替换素材或变速后的时长策略","type":"string"},"duration_us":{"description":"时长，单位微秒","type":"integer"},"edge":{"description":"IDL 预留字段；当前 operation 不读取","type":"string"},"effect_id":{"description":"贴纸效果 ID","type":"string"},"end_us":{"description":"时间线终点，单位微秒","type":"integer"},"from_segment_id":{"description":"转场前片段 ID","type":"string"},"mode":{"description":"项目原声模式","type":"string"},"op":{"description":"操作类型；必须是 capabilities 返回的受支持 operation","type":"string"},"operation_id":{"description":"调用方为本操作指定的唯一 ID","type":"string"},"placement":{"description":"放置策略：exact 或 slot","type":"string"},"playback_rate":{"description":"播放倍速","type":"number"},"preserve":{"description":"替换素材或变速时须完整提供的保留策略（点击展开查看详细字段）","properties":{"speed":{"description":"是否保留播放速度","type":"boolean"},"transform":{"description":"是否保留画面位置、尺寸和旋转","type":"boolean"},"volume":{"description":"是否保留音量","type":"boolean"}},"required":["transform","volume","speed"],"type":"object"},"preserve_pitch":{"description":"变速时是否保留音高","type":"boolean"},"ripple_mode":{"description":"碰撞策略：none 或 push_forward","type":"string"},"scope":{"description":"字幕样式作用域","type":"string"},"segment_id":{"description":"目标片段 ID","type":"string"},"source_end_us":{"description":"原素材出点，单位微秒","type":"integer"},"source_range":{"description":"时间范围，单位为微秒（点击展开查看详细字段）","properties":{"duration_us":{"description":"时长，单位为微秒","type":"integer"},"start_us":{"description":"起点时间，单位为微秒","type":"integer"}},"required":["start_us","duration_us"],"type":"object"},"source_start_us":{"description":"原素材入点，单位微秒","type":"integer"},"start_us":{"description":"时间线起点，单位微秒","type":"integer"},"style":{"description":"字幕样式预设","type":"string"},"style_patch":{"description":"文字样式局部补丁；省略字段保持原值（点击展开查看详细字段）","properties":{"background_color":{"description":"背景色","type":"string"},"clear_fields":{"description":"需要清除的可空视觉字段","items":{"description":"待清除的字段名","type":"string"},"type":"array"},"color":{"description":"文字颜色，#RRGGBB 或 #RRGGBBAA","type":"string"},"font_family":{"description":"字体名称","type":"string"},"font_size":{"description":"字号，范围由 capabilities 返回","type":"number"},"font_style":{"description":"字形，例如 normal 或 italic","type":"string"},"font_weight":{"description":"字重，例如 normal 或 bold","type":"string"},"letter_spacing":{"description":"字间距","type":"number"},"line_height":{"description":"行高","type":"number"},"opacity":{"description":"透明度，范围 0..1","type":"number"},"preset":{"description":"样式预设","type":"string"},"scale":{"description":"缩放比例","type":"number"},"shadow_blur":{"description":"阴影模糊半径","type":"number"},"shadow_color":{"description":"阴影颜色","type":"string"},"stroke_color":{"description":"描边颜色","type":"string"},"stroke_width":{"description":"描边宽度","type":"number"},"text_align":{"description":"文本对齐","type":"string"},"text_decoration":{"description":"文本装饰","type":"string"},"text_orientation":{"description":"字符朝向","type":"string"},"text_transform":{"description":"文本大小写转换","type":"string"},"writing_mode":{"description":"排版方向","type":"string"}},"type":"object"},"subtitle_segment_id":{"description":"单个字幕片段 ID","type":"string"},"subtitle_segment_ids":{"description":"字幕片段 ID 列表","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"target_track":{"description":"目标轨道；existing 使用已有轨道，new 自动创建轨道（点击展开查看详细字段）","properties":{"insert_after_track_id":{"description":"新轨道插入位置；省略则按服务端规则放置","type":"string"},"kind":{"description":"new 模式下的新轨道类型：video、sticker、subtitle、voiceover 或 bgm","type":"string"},"mode":{"description":"轨道选择模式：existing 或 new","enum":["existing","new"],"type":"string"},"track_id":{"description":"existing 模式下的稳定轨道 ID","type":"string"}},"required":["mode"],"type":"object"},"target_track_id":{"description":"目标轨道 ID","type":"string"},"text":{"description":"字幕或基础文字内容","type":"string"},"text_segment_id":{"description":"基础文字片段 ID","type":"string"},"text_transform":{"description":"文字位置与旋转（点击展开查看详细字段）","properties":{"rotation_degree":{"description":"顺时针旋转角度","type":"number"},"width":{"description":"文字区域宽度","type":"number"},"x":{"description":"文字锚点横坐标","type":"number"},"y":{"description":"文字锚点纵坐标","type":"number"}},"required":["x","y","width","rotation_degree"],"type":"object"},"title":{"description":"项目标题","type":"string"},"to_segment_id":{"description":"转场后片段 ID","type":"string"},"track_id":{"description":"边界或已有轨道 ID","type":"string"},"transform":{"description":"画面变换，使用画布像素坐标（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"左上角横坐标","type":"number"},"rotation_degree":{"description":"顺时针旋转角度","type":"number"},"top":{"description":"左上角纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"required":["left","top","width","height","rotation_degree"],"type":"object"},"transition_id":{"description":"转场素材 ID","type":"string"},"transition_type":{"description":"转场类型","type":"string"},"video_segment_id":{"description":"视频片段 ID","type":"string"},"volume":{"description":"音量，范围 0..2","type":"number"}},"required":["operation_id","op"],"type":"object"},"minItems":1,"type":"array"},"preview_id":{"description":"preview 接口返回的预演 ID","type":"string"},"reason":{"description":"本次编辑原因，供审计使用","type":"string"},"source_client_id":{"description":"调用方实例 ID，用于审计与抑制 WebSocket 回声","type":"string"}},"required":["contract_revision","expected_version","expected_edit_version","client_mutation_id","operations","preview_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑修改应用响应","properties":{"mutation":{"description":"视频编辑修改回执（点击展开查看详细字段）","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"base_edit_version":{"description":"修改前编辑版本","type":"integer"},"base_version":{"description":"修改前项目版本","type":"integer"},"client_mutation_id":{"description":"调用方幂等 ID","type":"string"},"created_at":{"description":"修改创建时间，RFC3339","format":"date-time","type":"string"},"mutation_id":{"description":"本次修改 ID","type":"string"},"noop":{"description":"是否为无实际变更的幂等结果","type":"boolean"},"operation_results":{"description":"各操作执行结果","items":{"description":"编辑操作执行结果（点击展开查看详细字段）","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"created_material_id":{"description":"新建素材 ID","type":"string"},"created_segment_id":{"description":"新建片段 ID","type":"string"},"created_track_display_code":{"description":"新建轨道显示编号","type":"string"},"created_track_id":{"description":"新建轨道 ID","type":"string"},"created_transition_id":{"description":"新建转场 ID","type":"string"},"normalized_playback_rate":{"description":"服务端规范化后的播放速度","type":"number"},"normalized_transform":{"description":"服务端规范化后的变换参数（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"画布横坐标","type":"number"},"rotation_degree":{"description":"旋转角度","type":"number"},"top":{"description":"画布纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"type":"object"},"op":{"description":"对应的操作类型","type":"string"},"operation_id":{"description":"对应的操作 ID","type":"string"},"removed_resource_ids":{"description":"已删除的资源 ID","items":{"description":"资源 ID","type":"string"},"type":"array"},"replaced_material_id":{"description":"被替换的素材 ID","type":"string"},"status":{"description":"执行状态","type":"string"},"warnings":{"description":"操作警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["operation_id","op","status"],"type":"object"},"type":"array"},"resulting_edit_version":{"description":"修改后的编辑版本","type":"integer"},"resulting_version":{"description":"修改后的项目版本","type":"integer"},"revertible":{"description":"该修改是否可以回退","type":"boolean"},"reverts_mutation_id":{"description":"本次回退所针对的原修改 ID","type":"string"},"warnings":{"description":"修改过程中的警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["mutation_id","client_mutation_id","base_version","base_edit_version","resulting_version","resulting_edit_version","operation_results","affected_ranges","warnings","noop","revertible","created_at"],"type":"object"}},"required":["mutation"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"应用视频编辑修改","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/edits/preview":{"post":{"description":"预演一组同步编辑操作，不写入项目。","operationId":"chuhaijiang-video-editor-edits-preview","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"预演同步编辑修改的请求","properties":{"client_mutation_id":{"description":"调用方幂等 ID；重试时必须复用","type":"string"},"contract_revision":{"description":"契约修订号，必须等于 capabilities 返回值","type":"string"},"expected_edit_version":{"description":"项目编辑版本，必须等于当前版本","type":"integer"},"expected_version":{"description":"项目内容版本，必须等于当前版本","type":"integer"},"operations":{"description":"按顺序执行的同步编辑操作","items":{"description":"单条同步编辑操作；op 决定哪些字段生效，完整操作与参数范围以 capabilities 返回为准（点击展开查看详细字段）","properties":{"asset_id":{"description":"用户素材库素材 ID","type":"string"},"asset_kind":{"description":"素材类型：video、image、audio 或 bgm","type":"string"},"at_us":{"description":"切分或边界时间点，单位微秒","type":"integer"},"catalog_revision":{"description":"贴纸目录版本","type":"string"},"duration_policy":{"description":"替换素材或变速后的时长策略","type":"string"},"duration_us":{"description":"时长，单位微秒","type":"integer"},"edge":{"description":"IDL 预留字段；当前 operation 不读取","type":"string"},"effect_id":{"description":"贴纸效果 ID","type":"string"},"end_us":{"description":"时间线终点，单位微秒","type":"integer"},"from_segment_id":{"description":"转场前片段 ID","type":"string"},"mode":{"description":"项目原声模式","type":"string"},"op":{"description":"操作类型；必须是 capabilities 返回的受支持 operation","type":"string"},"operation_id":{"description":"调用方为本操作指定的唯一 ID","type":"string"},"placement":{"description":"放置策略：exact 或 slot","type":"string"},"playback_rate":{"description":"播放倍速","type":"number"},"preserve":{"description":"替换素材或变速时须完整提供的保留策略（点击展开查看详细字段）","properties":{"speed":{"description":"是否保留播放速度","type":"boolean"},"transform":{"description":"是否保留画面位置、尺寸和旋转","type":"boolean"},"volume":{"description":"是否保留音量","type":"boolean"}},"required":["transform","volume","speed"],"type":"object"},"preserve_pitch":{"description":"变速时是否保留音高","type":"boolean"},"ripple_mode":{"description":"碰撞策略：none 或 push_forward","type":"string"},"scope":{"description":"字幕样式作用域","type":"string"},"segment_id":{"description":"目标片段 ID","type":"string"},"source_end_us":{"description":"原素材出点，单位微秒","type":"integer"},"source_range":{"description":"时间范围，单位为微秒（点击展开查看详细字段）","properties":{"duration_us":{"description":"时长，单位为微秒","type":"integer"},"start_us":{"description":"起点时间，单位为微秒","type":"integer"}},"required":["start_us","duration_us"],"type":"object"},"source_start_us":{"description":"原素材入点，单位微秒","type":"integer"},"start_us":{"description":"时间线起点，单位微秒","type":"integer"},"style":{"description":"字幕样式预设","type":"string"},"style_patch":{"description":"文字样式局部补丁；省略字段保持原值（点击展开查看详细字段）","properties":{"background_color":{"description":"背景色","type":"string"},"clear_fields":{"description":"需要清除的可空视觉字段","items":{"description":"待清除的字段名","type":"string"},"type":"array"},"color":{"description":"文字颜色，#RRGGBB 或 #RRGGBBAA","type":"string"},"font_family":{"description":"字体名称","type":"string"},"font_size":{"description":"字号，范围由 capabilities 返回","type":"number"},"font_style":{"description":"字形，例如 normal 或 italic","type":"string"},"font_weight":{"description":"字重，例如 normal 或 bold","type":"string"},"letter_spacing":{"description":"字间距","type":"number"},"line_height":{"description":"行高","type":"number"},"opacity":{"description":"透明度，范围 0..1","type":"number"},"preset":{"description":"样式预设","type":"string"},"scale":{"description":"缩放比例","type":"number"},"shadow_blur":{"description":"阴影模糊半径","type":"number"},"shadow_color":{"description":"阴影颜色","type":"string"},"stroke_color":{"description":"描边颜色","type":"string"},"stroke_width":{"description":"描边宽度","type":"number"},"text_align":{"description":"文本对齐","type":"string"},"text_decoration":{"description":"文本装饰","type":"string"},"text_orientation":{"description":"字符朝向","type":"string"},"text_transform":{"description":"文本大小写转换","type":"string"},"writing_mode":{"description":"排版方向","type":"string"}},"type":"object"},"subtitle_segment_id":{"description":"单个字幕片段 ID","type":"string"},"subtitle_segment_ids":{"description":"字幕片段 ID 列表","items":{"description":"字幕片段 ID","type":"string"},"type":"array"},"target_track":{"description":"目标轨道；existing 使用已有轨道，new 自动创建轨道（点击展开查看详细字段）","properties":{"insert_after_track_id":{"description":"新轨道插入位置；省略则按服务端规则放置","type":"string"},"kind":{"description":"new 模式下的新轨道类型：video、sticker、subtitle、voiceover 或 bgm","type":"string"},"mode":{"description":"轨道选择模式：existing 或 new","enum":["existing","new"],"type":"string"},"track_id":{"description":"existing 模式下的稳定轨道 ID","type":"string"}},"required":["mode"],"type":"object"},"target_track_id":{"description":"目标轨道 ID","type":"string"},"text":{"description":"字幕或基础文字内容","type":"string"},"text_segment_id":{"description":"基础文字片段 ID","type":"string"},"text_transform":{"description":"文字位置与旋转（点击展开查看详细字段）","properties":{"rotation_degree":{"description":"顺时针旋转角度","type":"number"},"width":{"description":"文字区域宽度","type":"number"},"x":{"description":"文字锚点横坐标","type":"number"},"y":{"description":"文字锚点纵坐标","type":"number"}},"required":["x","y","width","rotation_degree"],"type":"object"},"title":{"description":"项目标题","type":"string"},"to_segment_id":{"description":"转场后片段 ID","type":"string"},"track_id":{"description":"边界或已有轨道 ID","type":"string"},"transform":{"description":"画面变换，使用画布像素坐标（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"左上角横坐标","type":"number"},"rotation_degree":{"description":"顺时针旋转角度","type":"number"},"top":{"description":"左上角纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"required":["left","top","width","height","rotation_degree"],"type":"object"},"transition_id":{"description":"转场素材 ID","type":"string"},"transition_type":{"description":"转场类型","type":"string"},"video_segment_id":{"description":"视频片段 ID","type":"string"},"volume":{"description":"音量，范围 0..2","type":"number"}},"required":["operation_id","op"],"type":"object"},"minItems":1,"type":"array"},"reason":{"description":"本次编辑原因，供审计使用","type":"string"},"source_client_id":{"description":"调用方实例 ID，用于审计与抑制 WebSocket 回声","type":"string"}},"required":["contract_revision","expected_version","expected_edit_version","client_mutation_id","operations"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑预演响应","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"base_edit_version":{"description":"预演所基于的编辑版本","type":"integer"},"base_version":{"description":"预演所基于的项目内容版本","type":"integer"},"can_apply":{"description":"是否可以应用该预演","type":"boolean"},"estimated_charge":{"description":"预估费用（点击展开查看详细字段）","properties":{"amount":{"description":"预估金额","type":"integer"},"unit":{"description":"金额单位","type":"string"}},"type":"object"},"expires_at":{"description":"预演过期时间，RFC3339","format":"date-time","type":"string"},"normalized_operations":{"description":"服务端规范化后的编辑操作","items":{"description":"标准化后的编辑操作（点击展开查看详细字段）","properties":{"asset_id":{"description":"素材 ID","type":"string"},"asset_kind":{"description":"素材类型","type":"string"},"duration_us":{"description":"持续时间，单位微秒","type":"integer"},"end_us":{"description":"时间线终点，单位微秒","type":"integer"},"from_segment_id":{"description":"转场起始片段 ID","type":"string"},"op":{"description":"操作类型","enum":["move_segment","resize_segment","trim_segment","split_segment","delete_segment","set_transition","remove_transition","update_transition_duration","set_segment_volume","set_project_source_audio","restore_video_audio","upsert_subtitle","delete_subtitle","update_subtitle_style","insert_asset_segment","replace_segment_asset","update_segment_transform","set_segment_speed","upsert_text","insert_sticker","update_project"],"type":"string"},"operation_id":{"description":"调用方提供的操作 ID","type":"string"},"playback_rate":{"description":"播放速度","type":"number"},"preserve_pitch":{"description":"变速时是否保持音高","type":"boolean"},"segment_id":{"description":"目标片段 ID","type":"string"},"source_range":{"description":"素材源区间（点击展开查看详细字段）","properties":{"duration_us":{"description":"持续时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"start_us":{"description":"时间线起点，单位微秒","type":"integer"},"target_track":{"description":"目标轨道（点击展开查看详细字段）","properties":{"insert_after_track_id":{"description":"新轨道插入位置","type":"string"},"kind":{"description":"new 模式下的新轨道类型","type":"string"},"mode":{"description":"轨道选择模式","enum":["existing","new"],"type":"string"},"track_id":{"description":"existing 模式下的轨道 ID","type":"string"}},"type":"object"},"target_track_id":{"description":"目标轨道 ID","type":"string"},"text":{"description":"文本内容","type":"string"},"title":{"description":"项目标题","type":"string"},"to_segment_id":{"description":"转场结束片段 ID","type":"string"},"track_id":{"description":"轨道 ID","type":"string"},"transform":{"description":"画面变换参数（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"画布横坐标","type":"number"},"rotation_degree":{"description":"旋转角度","type":"number"},"top":{"description":"画布纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"type":"object"},"transition_type":{"description":"转场类型","type":"string"},"volume":{"description":"音量","type":"number"}},"required":["operation_id","op"],"type":"object"},"type":"array"},"operation_results":{"description":"各操作预演结果","items":{"description":"编辑操作执行结果（点击展开查看详细字段）","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"created_material_id":{"description":"新建素材 ID","type":"string"},"created_segment_id":{"description":"新建片段 ID","type":"string"},"created_track_display_code":{"description":"新建轨道显示编号","type":"string"},"created_track_id":{"description":"新建轨道 ID","type":"string"},"created_transition_id":{"description":"新建转场 ID","type":"string"},"normalized_playback_rate":{"description":"服务端规范化后的播放速度","type":"number"},"normalized_transform":{"description":"服务端规范化后的变换参数（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"画布横坐标","type":"number"},"rotation_degree":{"description":"旋转角度","type":"number"},"top":{"description":"画布纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"type":"object"},"op":{"description":"对应的操作类型","type":"string"},"operation_id":{"description":"对应的操作 ID","type":"string"},"removed_resource_ids":{"description":"已删除的资源 ID","items":{"description":"资源 ID","type":"string"},"type":"array"},"replaced_material_id":{"description":"被替换的素材 ID","type":"string"},"status":{"description":"执行状态","type":"string"},"warnings":{"description":"操作警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["operation_id","op","status"],"type":"object"},"type":"array"},"preview_id":{"description":"预演 ID；应用修改时必须回传","type":"string"},"warnings":{"description":"预演警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["preview_id","expires_at","base_version","base_edit_version","normalized_operations","operation_results","affected_ranges","warnings","estimated_charge","can_apply"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"预演视频编辑修改","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/mutations/{mutation_id}/revert":{"post":{"description":"安全回退一次已应用的项目修改。","operationId":"chuhaijiang-video-editor-mutation-revert","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"待回退的修改 ID","in":"path","name":"mutation_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"回退项目修改的请求","properties":{"client_mutation_id":{"description":"调用方幂等 ID","type":"string"},"expected_edit_version":{"description":"项目编辑版本","type":"integer"},"expected_version":{"description":"项目内容版本","type":"integer"},"reason":{"description":"回退原因","type":"string"},"source_client_id":{"description":"调用方实例 ID","type":"string"}},"required":["expected_version","expected_edit_version","client_mutation_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑修改回退响应","properties":{"mutation":{"description":"视频编辑修改回执（点击展开查看详细字段）","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"base_edit_version":{"description":"修改前编辑版本","type":"integer"},"base_version":{"description":"修改前项目版本","type":"integer"},"client_mutation_id":{"description":"调用方幂等 ID","type":"string"},"created_at":{"description":"修改创建时间，RFC3339","format":"date-time","type":"string"},"mutation_id":{"description":"本次修改 ID","type":"string"},"noop":{"description":"是否为无实际变更的幂等结果","type":"boolean"},"operation_results":{"description":"各操作执行结果","items":{"description":"编辑操作执行结果（点击展开查看详细字段）","properties":{"affected_ranges":{"description":"受影响的时间线范围","items":{"description":"受影响的时间线范围（点击展开查看详细字段）","properties":{"end_us":{"description":"结束时间，单位微秒","type":"integer"},"start_us":{"description":"起始时间，单位微秒","type":"integer"}},"type":"object"},"type":"array"},"created_material_id":{"description":"新建素材 ID","type":"string"},"created_segment_id":{"description":"新建片段 ID","type":"string"},"created_track_display_code":{"description":"新建轨道显示编号","type":"string"},"created_track_id":{"description":"新建轨道 ID","type":"string"},"created_transition_id":{"description":"新建转场 ID","type":"string"},"normalized_playback_rate":{"description":"服务端规范化后的播放速度","type":"number"},"normalized_transform":{"description":"服务端规范化后的变换参数（点击展开查看详细字段）","properties":{"height":{"description":"显示高度","type":"number"},"left":{"description":"画布横坐标","type":"number"},"rotation_degree":{"description":"旋转角度","type":"number"},"top":{"description":"画布纵坐标","type":"number"},"width":{"description":"显示宽度","type":"number"}},"type":"object"},"op":{"description":"对应的操作类型","type":"string"},"operation_id":{"description":"对应的操作 ID","type":"string"},"removed_resource_ids":{"description":"已删除的资源 ID","items":{"description":"资源 ID","type":"string"},"type":"array"},"replaced_material_id":{"description":"被替换的素材 ID","type":"string"},"status":{"description":"执行状态","type":"string"},"warnings":{"description":"操作警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["operation_id","op","status"],"type":"object"},"type":"array"},"resulting_edit_version":{"description":"修改后的编辑版本","type":"integer"},"resulting_version":{"description":"修改后的项目版本","type":"integer"},"revertible":{"description":"该修改是否可以回退","type":"boolean"},"reverts_mutation_id":{"description":"本次回退所针对的原修改 ID","type":"string"},"warnings":{"description":"修改过程中的警告","items":{"description":"操作警告（点击展开查看详细字段）","properties":{"code":{"description":"警告代码","type":"string"},"message":{"description":"警告说明","type":"string"},"operation_id":{"description":"关联的操作 ID","type":"string"},"resource_id":{"description":"关联资源 ID","type":"string"}},"type":"object"},"type":"array"}},"required":["mutation_id","client_mutation_id","base_version","base_edit_version","resulting_version","resulting_edit_version","operation_results","affected_ranges","warnings","noop","revertible","created_at"],"type":"object"}},"required":["mutation"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"回退视频编辑修改","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/renders":{"post":{"description":"按指定编辑版本提交项目成片渲染。","operationId":"chuhaijiang-video-editor-renders-submit","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"提交项目渲染的请求","properties":{"expected_edit_version":{"description":"要渲染的项目编辑版本","type":"integer"},"idempotency_key":{"description":"渲染幂等 ID","type":"string"},"mode":{"description":"渲染模式，当前仅支持 full_export","enum":["full_export"],"type":"string"},"profile":{"description":"渲染质量配置（点击展开查看详细字段）","properties":{"max_width":{"description":"draft 渲染最大宽度；320..1920 的偶数","type":"integer"},"quality":{"description":"质量：draft 或 production","enum":["draft","production"],"type":"string"}},"required":["quality"],"type":"object"}},"required":["mode","expected_edit_version","idempotency_key","profile"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"项目渲染提交响应","properties":{"edit_version":{"description":"实际提交的编辑版本","type":"integer"},"project_id":{"description":"项目 ID","type":"string"},"reused":{"description":"是否复用了已有渲染","type":"boolean"},"status":{"description":"任务状态；首次提交为 assembling","type":"string"},"task_id":{"description":"平台视频任务 ID","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"202":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"项目渲染提交响应","properties":{"edit_version":{"description":"实际提交的编辑版本","type":"integer"},"project_id":{"description":"项目 ID","type":"string"},"reused":{"description":"是否复用了已有渲染","type":"boolean"},"status":{"description":"任务状态；首次提交为 assembling","type":"string"},"task_id":{"description":"平台视频任务 ID","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Accepted: asynchronous processing is in progress"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"提交视频编辑项目渲染","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.write"}},"/open/v1/video-editor/projects/{project_id}/renders/list":{"post":{"description":"查询指定视频编辑项目的渲染记录、状态、产物和失败信息；presign=true 时在产物可用后返回临时下载地址。","operationId":"chuhaijiang-video-editor-renders-list","parameters":[{"description":"目标项目 ID","in":"path","name":"project_id","required":true,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"渲染记录查询条件","properties":{"presign":{"default":false,"description":"产物可用时是否返回临时下载地址","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123"},"schema":{"properties":{"data":{"description":"视频编辑项目渲染记录响应","properties":{"exports":{"description":"项目的渲染记录列表，按服务端顺序返回","items":{"description":"单次项目渲染记录（点击展开查看详细字段）","properties":{"async_task_id":{"description":"渲染任务 ID，与提交项目渲染接口返回的 task_id 对应","type":"string"},"created_at":{"description":"创建时间，RFC3339","type":"string"},"duration_seconds":{"description":"成片时长，单位秒","type":"number"},"edit_version":{"description":"该产物对应的项目编辑版本","type":"integer"},"error":{"description":"渲染失败原因","type":"string"},"export_version":{"description":"导出版本","type":"integer"},"id":{"description":"导出记录 ID","type":"string"},"plan_id":{"description":"所属项目 ID","type":"string"},"status":{"description":"渲染状态","enum":["pending","assembling","ready","failed"],"type":"string"},"updated_at":{"description":"更新时间，RFC3339","type":"string"},"video_os_bucket":{"description":"成片的稳定对象存储 Bucket，可作为创建项目视频素材的 video_os_bucket 传入","type":"string"},"video_os_key":{"description":"成片的稳定对象存储 Key，可作为创建项目视频素材的 video_os_key 传入","type":"string"},"video_url":{"description":"presign=true 且产物可用时的临时下载地址","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"查询视频编辑项目渲染记录","tags":["内容制作/6.视频编辑"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.video_editor.read"}},"/open/v1/videos/search":{"get":{"description":"搜索 TikTok 带货视频，支持播放量、GMV、互动率等多维度过滤","operationId":"chuhaijiang-videos-search","parameters":[{"description":"搜索关键词","example":"phone case","in":"query","name":"keyword","required":false,"schema":{"type":"string"}},{"description":"视频分类ID","example":"100001","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"是否为带货视频","example":false,"in":"query","name":"is_commercial","required":false,"schema":{"type":"boolean"}},{"description":"最低播放量","example":1000,"in":"query","name":"min_views","required":false,"schema":{"type":"number"}},{"description":"最高播放量","example":1000000,"in":"query","name":"max_views","required":false,"schema":{"type":"number"}},{"description":"最低点赞数","example":100,"in":"query","name":"min_likes","required":false,"schema":{"type":"number"}},{"description":"最高点赞数","example":100000,"in":"query","name":"max_likes","required":false,"schema":{"type":"number"}},{"description":"30天最低GMV（美元）","example":1000,"in":"query","name":"min_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"30天最高GMV（美元）","example":100000,"in":"query","name":"max_gmv_30d","required":false,"schema":{"type":"number"}},{"description":"最低互动率（0-1）","example":0.01,"in":"query","name":"min_engagement","required":false,"schema":{"type":"number"}},{"description":"最高互动率（0-1）","example":0.1,"in":"query","name":"max_engagement","required":false,"schema":{"type":"number"}},{"description":"排序，格式: field:asc|desc。支持: engagement, gmv_30d, launch_time, likes, sold_30d, views。默认: views:desc","example":"views:desc","in":"query","name":"sort","required":false,"schema":{"default":"views:desc","enum":["engagement","gmv_30d","launch_time","likes","sold_30d","views"],"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"账号类型","type":"integer"},"author_category_label":{"description":"作者分类标签","type":"string"},"author_id":{"description":"作者用户ID","type":"string"},"author_nickname":{"description":"作者昵称","type":"string"},"author_unique_id":{"description":"作者TikTok用户名","type":"string"},"country_code":{"description":"国家代码","type":"string"},"follow_cnt":{"description":"粉丝数","type":"integer"},"id":{"description":"唯一标识","type":"string"},"is_ad":{"description":"是否广告投放","type":"boolean"},"is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"product_id":{"description":"商品ID","type":"string"},"product_l1_category":{"description":"商品一级类目","type":"string"},"product_l2_category":{"description":"商品二级类目","type":"string"},"product_l3_category":{"description":"商品三级类目","type":"string"},"product_title":{"description":"商品标题","type":"string"},"share_url":{"description":"TikTok分享链接","type":"string"},"video_30d_gmv":{"description":"近30天视频GMV","type":"string"},"video_30d_gpm":{"description":"近30天视频GPM","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"video_30d_sold_count":{"description":"近30天视频带货销量","type":"string"},"video_ceiling_price":{"description":"视频关联商品最高价","type":"string"},"video_collect_count":{"description":"收藏数","type":"integer"},"video_comment_count":{"description":"评论数","type":"integer"},"video_commission_rate":{"description":"视频关联商品佣金率","type":"string"},"video_desc":{"description":"视频描述","type":"string"},"video_duration":{"description":"视频时长(ms)","type":"integer"},"video_engagement_rate":{"description":"互动率(0-1)","type":"number"},"video_floor_price":{"description":"视频关联商品最低价","type":"string"},"video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"video_like_count":{"description":"点赞数","type":"integer"},"video_play_count":{"description":"播放量","type":"integer"},"video_product_total_gmv":{"description":"视频关联商品总GMV","type":"string"},"video_product_total_sold_count":{"description":"视频关联商品总销量","type":"string"},"video_share_count":{"description":"分享数","type":"integer"},"video_total_like_count_to_follower_count_ratio":{"description":"总点赞数/粉丝数比值","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频搜索","tags":["数据查询/3.视频数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.videos.read"}},"/open/v1/videos/{id}":{"get":{"description":"获取 TikTok 视频详情，含关联商品","operationId":"chuhaijiang-videos-detail","parameters":[{"description":"视频ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"包含关联资源，逗号分隔（可选值: core(核心指标)）","in":"query","name":"include","required":false,"schema":{"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":6}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"account_type":{"description":"账号类型","type":"integer"},"author_avg_engagement_rate":{"description":"平均互动率","type":"number"},"country_code":{"description":"国家代码","type":"string"},"follower_count":{"description":"粉丝数","type":"integer"},"had_product":{"description":"是否带货","type":"boolean"},"has_comment":{"description":"是否有评论","type":"boolean"},"id":{"description":"唯一标识","type":"string"},"is_ad":{"description":"是否广告投放","type":"boolean"},"is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"last_update_time":{"description":"最后更新时间(ms时间戳)","type":"integer"},"nickname":{"description":"昵称","type":"string"},"product_category_label_list":{"description":"商品分类标签列表","type":"string"},"share_url":{"description":"TikTok分享链接","type":"string"},"uid":{"description":"用户ID","type":"string"},"unique_id":{"description":"TikTok 用户名","type":"string"},"user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"video_avg_like_count":{"description":"视频平均点赞数","type":"number"},"video_avg_play_count":{"description":"视频平均播放量","type":"number"},"video_count":{"description":"视频数","type":"integer"},"video_cover":{"description":"视频封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"video_desc":{"description":"视频描述","type":"string"},"video_duration":{"description":"视频时长(ms)","type":"integer"},"video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频详情","tags":["数据查询/3.视频数据"],"x-billing-mode":"per_call","x-coin-cost":6,"x-scope":"chuhaijiang.videos.read"}},"/open/v1/videos/{id}/products":{"get":{"description":"","operationId":"chuhaijiang-videos-products","parameters":[{"description":"视频ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_product_detail_ceiling_price":{"description":"最高价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_commission_rate":{"description":"佣金率","type":"number"},"tiktok_product_detail_floor_price":{"description":"最低价","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_product_detail_l1_category":{"description":"一级类目","type":"string"},"tiktok_product_detail_l2_category":{"description":"二级类目","type":"string"},"tiktok_product_detail_l3_category":{"description":"三级类目","type":"string"},"tiktok_product_detail_product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_name":{"description":"商品名称","type":"string"},"tiktok_product_detail_product_rating":{"description":"商品评分(0-5)","type":"number"},"tiktok_product_detail_product_sku_props":{"description":"SKU属性","items":{"properties":{"has_image":{"description":"是否有图片","type":"boolean"},"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名","type":"string"},"sale_prop_values":{"description":"属性值列表","items":{"properties":{"image":{"properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_skus":{"description":"SKU列表","items":{"properties":{"is_hot":{"description":"是否热销","type":"boolean"},"price":{"properties":{"discount":{"description":"折扣信息","type":"string"},"original_price":{"description":"原价","type":"string"},"original_price_value":{"description":"原价数值","type":"string"},"real_price":{"description":"实际价格","type":"number"},"unit_price_desc":{"description":"单价描述","type":"string"}},"type":"object"},"sale_prop_value_ids":{"description":"属性值ID组合","type":"string"},"sku_id":{"description":"SKU ID","type":"string"},"sku_sale_props":{"description":"SKU属性","items":{"properties":{"prop_id":{"description":"属性ID","type":"string"},"prop_name":{"description":"属性名(如Color)","type":"string"},"prop_value":{"description":"属性值","type":"string"},"prop_value_id":{"description":"属性值ID","type":"string"}},"type":"object"},"type":"array"},"status":{"description":"状态(1=在售)","type":"integer"},"stock":{"description":"库存","type":"integer"}},"type":"object"},"type":"array"},"tiktok_product_detail_product_status":{"description":"商品状态","type":"integer"},"tiktok_product_detail_region":{"description":"地区代码","type":"string"},"tiktok_video_detail_product_country_code":{"description":"商品所在国家","type":"string"},"tiktok_video_detail_product_id":{"description":"商品ID","type":"string"},"tiktok_video_detail_product_launch_time":{"description":"商品上架时间(ms时间戳)","type":"integer"},"tiktok_video_detail_product_total_gmv":{"description":"商品总GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_video_detail_product_total_sold_count":{"description":"商品总销量","type":"integer"},"tiktok_video_detail_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_video_detail_video_30d_sold_count":{"description":"近30天视频带货销量","type":"integer"},"tiktok_video_detail_video_id":{"description":"视频ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频带货商品","tags":["数据查询/3.视频数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.videos.read"}},"/open/v1/videos/{id}/reviews":{"get":{"description":"","operationId":"chuhaijiang-videos-reviews","parameters":[{"description":"视频ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_video_detail_comment_create_time":{"description":"上架时间","type":"integer"},"tiktok_video_detail_comment_id":{"description":"唯一标识","type":"string"},"tiktok_video_detail_comment_like_count":{"description":"点赞数","type":"integer"},"tiktok_video_detail_comment_nickname":{"description":"昵称","type":"string"},"tiktok_video_detail_comment_reply_count":{"description":"回复数","type":"integer"},"tiktok_video_detail_comment_text":{"description":"文本内容","type":"string"},"tiktok_video_detail_comment_unique_id":{"description":"TikTok 用户名","type":"string"},"tiktok_video_detail_comment_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_video_detail_video_id":{"description":"视频ID","type":"string"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"视频评论","tags":["数据查询/3.视频数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.videos.read"}},"/open/v1/videos/{id}/similar":{"get":{"description":"","operationId":"chuhaijiang-videos-similar","parameters":[{"description":"视频ID","example":"1234567890","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"页码，默认 1","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"每页数量，默认 10，最大 10","in":"query","name":"page_size","required":false,"schema":{"default":10,"maximum":10,"type":"integer"}},{"description":"路由参数：按 country 值路由到不同后端服务","in":"query","name":"country","required":true,"schema":{"enum":["br","de","es","fr","gb","id","it","jp","mx","my","ph","sg","th","us","vn"],"type":"string"}},{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":9999,"credits_cost":12}},"schema":{"properties":{"data":{"properties":{"items":{"items":{"properties":{"id":{"description":"唯一标识","type":"string"},"tiktok_video_detail_similar_author_nickname":{"description":"作者昵称","type":"string"},"tiktok_video_detail_similar_author_uid":{"description":"作者用户ID","type":"string"},"tiktok_video_detail_similar_author_unique_id":{"description":"作者TikTok用户名","type":"string"},"tiktok_video_detail_similar_category_label":{"description":"达人分类标签","type":"string"},"tiktok_video_detail_similar_country_code":{"description":"国家代码","type":"string"},"tiktok_video_detail_similar_follower_cnt":{"description":"粉丝数","type":"integer"},"tiktok_video_detail_similar_is_aigc_video":{"description":"是否AI生成视频","type":"boolean"},"tiktok_video_detail_similar_product_id":{"description":"商品ID","type":"string"},"tiktok_video_detail_similar_product_images":{"description":"商品图片","type":"string"},"tiktok_video_detail_similar_product_l1_category":{"description":"商品一级类目","type":"string"},"tiktok_video_detail_similar_product_l2_category":{"description":"商品二级类目","type":"string"},"tiktok_video_detail_similar_product_l3_category":{"description":"商品三级类目","type":"string"},"tiktok_video_detail_similar_product_title":{"description":"商品标题","type":"string"},"tiktok_video_detail_similar_share_url":{"description":"TikTok分享链接","type":"string"},"tiktok_video_detail_similar_user_avatar":{"description":"用户头像","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_video_detail_similar_video_30d_gmv":{"description":"近30天视频GMV","properties":{"unit":{"description":"货币代码(如US)","type":"string"},"value":{"description":"金额","type":"number"}},"type":"object"},"tiktok_video_detail_similar_video_comment_count":{"description":"评论数","type":"integer"},"tiktok_video_detail_similar_video_cover":{"description":"视频封面","properties":{"thumb_url":{"description":"缩略图链接","type":"string"},"url":{"description":"图片链接","type":"string"}},"type":"object"},"tiktok_video_detail_similar_video_desc":{"description":"视频描述","type":"string"},"tiktok_video_detail_similar_video_duration":{"description":"视频时长(ms)","type":"integer"},"tiktok_video_detail_similar_video_id":{"description":"视频ID","type":"string"},"tiktok_video_detail_similar_video_launch_time":{"description":"发布时间(ms时间戳)","type":"integer"},"tiktok_video_detail_similar_video_like_count":{"description":"点赞数","type":"integer"},"tiktok_video_detail_similar_video_play_count":{"description":"播放量","type":"integer"},"tiktok_video_detail_similar_video_share_count":{"description":"分享数","type":"integer"}},"type":"object"},"type":"array"},"total_count":{"description":"结果总数","type":"integer"}},"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"example":{"code":"BAD_REQUEST","message":"Invalid request parameters","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"example":{"code":"AUTH_INVALID_KEY","message":"The API key provided is invalid or has been revoked","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"example":{"code":"INSUFFICIENT_CREDITS","message":"Your account has insufficient credits for this request","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Insufficient credits"},"403":{"content":{"application/json":{"example":{"code":"FORBIDDEN_SCOPE","message":"Your API key does not have permission to access this resource","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"example":{"code":"ROUTE_NOT_FOUND","message":"The requested resource was not found","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Not found"},"429":{"content":{"application/json":{"example":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Rate limit exceeded"},"500":{"content":{"application/json":{"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred on the server","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Internal server error"},"502":{"content":{"application/json":{"example":{"code":"BACKEND_ERROR","message":"The upstream service returned an invalid response","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Bad gateway"},"503":{"content":{"application/json":{"example":{"code":"BACKEND_UNAVAILABLE","message":"The upstream service is temporarily unavailable","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Service unavailable"},"504":{"content":{"application/json":{"example":{"code":"BACKEND_TIMEOUT","message":"The upstream service did not respond in time","request_id":"req_example"},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"Gateway timeout"}},"summary":"相似视频","tags":["数据查询/3.视频数据"],"x-billing-mode":"per_call","x-coin-cost":12,"x-scope":"chuhaijiang.videos.read"}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"servers":[{"description":"生产环境","url":"https://openapi.gateway.chuhaijiang.com"}],"tags":[{"description":"接口中所有 `*_url` 字段需要公网可访问的地址；如需上传本地文件，请先通过「文件上传」分类下的「生成上传预签名URL」接口获取。","name":"内容制作/1.AI 视频"},{"description":"接口中所有 `*_url` 字段需要公网可访问的地址；如需上传本地文件，请先通过「文件上传」分类下的「生成上传预签名URL」接口获取。","name":"内容制作/2.AI 图片"},{"name":"内容制作/3.AI 文案"},{"name":"内容制作/4.AI 分析"},{"name":"内容制作/5.AI 画布"},{"name":"内容制作/6.视频编辑"},{"description":"AI 对话式 agent 入口（Server-Sent Events 流式响应）。","name":"小匠Agent/1.对话"},{"description":"会话与报告只读查询：列会话、取会话消息、取会话报告、取单个报告详情。免费接口。","name":"小匠Agent/2.会话与报告"},{"name":"广告营销/1.广告账户"},{"name":"广告营销/2.常规投放"},{"name":"广告营销/3.GMV MAX"},{"description":"## 异步任务使用流程\n\n1. 提交任务（如 POST /open/v1/ai/videos/content-analysis）→ 返回 task_id\n2. 轮询状态：GET /open/v1/tasks/{task_id}\n   - status=\"running\" → 继续轮询（建议间隔 3-5 秒）\n   - status=\"success\" → result 字段包含完整结果\n   - status=\"failed\" → error_message 字段包含错误信息\n3. 成功的任务结果会持久化，可以随时再次查询\n\n\u003e 以下接口为异步任务：所有 AI 分析、AI 生成类接口。\n\u003e 提交后立即返回 task_id，不会阻塞等待。","name":"异步任务"},{"description":"## 商品分类 ID 参考\n\n搜索接口的 `category` 参数需要传分类 ID（数字）。以下为 TikTok 一级分类列表：\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| 601450 | 美妆个护 |\n| 601152 | 女士服装 |\n| 700645 | 保健 |\n| 603014 | 运动与户外 |\n| 601739 | 手机与数码 |\n| 600942 | 家电 |\n| 824328 | 男士服装 |\n| 605248 | 时尚配件 |\n| 700437 | 食品饮料 |\n| 600001 | 居家日用 |\n| 604453 | 家具 |\n| 600024 | 厨房用品 |\n| 600154 | 家纺布艺 |\n| 824584 | 箱包 |\n| 604206 | 玩具和爱好 |\n| 601352 | 鞋靴 |\n| 604579 | 五金工具 |\n| 604968 | 家装建材 |\n| 602118 | 宠物用品 |\n| 601755 | 电脑办公 |\n| 602284 | 母婴用品 |\n| 605196 | 汽车与摩托车 |\n| 951432 | 收藏品 |\n| 801928 | 图书/杂志/影音 |\n| 953224 | 珠宝与衍生品 |\n| 856720 | 二手商品 |\n| 802184 | 儿童时尚 |\n\n\u003e 以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有商品。","name":"数据查询/1.商品数据"},{"description":"## 参数说明\n\n- `category`：达人分类 ID（达人内容领域标签，与商品分类是两套不同体系），可选值见下方「达人分类 ID 参考」。也可不传此参数搜索，从返回结果的 `category_label` 字段获取分类 ID 后再用于精确筛选。\n- `has_contact`：是否有联系方式（true/false），筛选有公开邮箱/社交账号的达人\n\n## 达人分类 ID 参考\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| creator_category_v20240616_8 | 购物与零售 |\n| creator_category_v20240616_15 | 媒体与娱乐 |\n| creator_category_v20240616_10 | 美妆与时尚 |\n| creator_category_v20240616_14 | 个人博主 |\n| creator_category_v20240616_12 | 服装与配饰 |\n| creator_category_v20240616_32 | 公众人物 |\n| creator_category_v20240616_23 | 艺术与手工 |\n| creator_category_v20240616_17 | 运动与健身 |\n| creator_category_v20240616_24 | 健康与养生 |\n| creator_category_v20240616_13 | 音乐与舞蹈 |\n| creator_category_v20240616_9 | 家居、家具与家电 |\n| creator_category_v20240616_19 | 宠物与动物 |\n| creator_category_v20240616_18 | 教育 |\n| creator_category_v20240616_11 | 美食与饮品 |\n| creator_category_v20240616_31 | 汽车与交通 |\n| creator_category_v20240616_5 | 电子产品 |\n| creator_category_v20240616_29 | 游戏 |\n| creator_category_v20240616_30 | 专业服务 |\n| creator_category_v20240616_16 | 母婴 |\n| creator_category_v20240616_33 | 美食与烹饪 |\n| creator_category_v20240616_20 | 旅游与出行 |\n| creator_category_v20240616_27 | 金融与投资 |\n| creator_category_v20240616_2 | 机械与设备 |\n| creator_category_v20240616_21 | 品牌 |\n| creator_category_v20240616_25 | 咨询与服务 |\n| creator_category_v20240616_4 | 房产 |\n| creator_category_v20240616_28 | 政府与政治 |\n| creator_category_v20240616_6 | 餐厅与酒吧 |\n| creator_category_v20240616_26 | IT 与高科技 |\n| creator_category_v20240616_22 | 软件与应用 |\n| creator_category_v20240616_3 | 直播公会 |\n| creator_category_v20240616_7 | 影视与制片 |\n| creator_category_v20240616_34 | 其他 |\n\n\u003e 达人分类与主播（直播）分类共用同一套体系，上表同样适用于「直播数据」的 `category` 参数。","name":"数据查询/2.达人数据"},{"description":"## 参数说明\n\n- `is_commercial`：是否为带货视频（true/false）\n\n## 商品分类 ID 参考\n\n`category` 参数为视频关联的商品分类 ID：\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| 601450 | 美妆个护 |\n| 601152 | 女士服装 |\n| 700645 | 保健 |\n| 603014 | 运动与户外 |\n| 601739 | 手机与数码 |\n| 600942 | 家电 |\n| 824328 | 男士服装 |\n| 605248 | 时尚配件 |\n| 700437 | 食品饮料 |\n| 600001 | 居家日用 |\n| 604453 | 家具 |\n| 600024 | 厨房用品 |\n| 600154 | 家纺布艺 |\n| 824584 | 箱包 |\n| 604206 | 玩具和爱好 |\n| 601352 | 鞋靴 |\n| 604579 | 五金工具 |\n| 604968 | 家装建材 |\n| 602118 | 宠物用品 |\n| 601755 | 电脑办公 |\n| 602284 | 母婴用品 |\n| 605196 | 汽车与摩托车 |\n| 951432 | 收藏品 |\n| 801928 | 图书/杂志/影音 |\n| 953224 | 珠宝与衍生品 |\n| 856720 | 二手商品 |\n| 802184 | 儿童时尚 |\n\n\u003e 以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有视频。","name":"数据查询/3.视频数据"},{"description":"## 参数说明\n\n- `seller_type`：卖家类型（1=海外非品牌, 2=本地, 3=品牌, 4=非品牌）\n\n## 商品分类 ID 参考\n\n`category` 参数为店铺主营商品分类 ID，与商品搜索使用同一套分类体系：\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| 601450 | 美妆个护 |\n| 601152 | 女士服装 |\n| 700645 | 保健 |\n| 603014 | 运动与户外 |\n| 601739 | 手机与数码 |\n| 600942 | 家电 |\n| 824328 | 男士服装 |\n| 605248 | 时尚配件 |\n| 700437 | 食品饮料 |\n| 600001 | 居家日用 |\n| 604453 | 家具 |\n| 600024 | 厨房用品 |\n| 600154 | 家纺布艺 |\n| 824584 | 箱包 |\n| 604206 | 玩具和爱好 |\n| 601352 | 鞋靴 |\n| 604579 | 五金工具 |\n| 604968 | 家装建材 |\n| 602118 | 宠物用品 |\n| 601755 | 电脑办公 |\n| 602284 | 母婴用品 |\n| 605196 | 汽车与摩托车 |\n| 951432 | 收藏品 |\n| 801928 | 图书/杂志/影音 |\n| 953224 | 珠宝与衍生品 |\n| 856720 | 二手商品 |\n| 802184 | 儿童时尚 |\n\n\u003e 以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有店铺。","name":"数据查询/4.店铺数据"},{"name":"数据查询/5.广告与创意情报"},{"description":"## 参数说明\n\n- `category`：主播分类 ID，与达人分类使用同一套体系，可选值见下方「主播分类 ID 参考」。也可不传此参数搜索。\n- `is_living`：是否正在直播（true/false）\n- `is_commercial`：是否为带货直播（true/false）\n\n## 主播分类 ID 参考\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| creator_category_v20240616_8 | 购物与零售 |\n| creator_category_v20240616_15 | 媒体与娱乐 |\n| creator_category_v20240616_10 | 美妆与时尚 |\n| creator_category_v20240616_14 | 个人博主 |\n| creator_category_v20240616_12 | 服装与配饰 |\n| creator_category_v20240616_32 | 公众人物 |\n| creator_category_v20240616_23 | 艺术与手工 |\n| creator_category_v20240616_17 | 运动与健身 |\n| creator_category_v20240616_24 | 健康与养生 |\n| creator_category_v20240616_13 | 音乐与舞蹈 |\n| creator_category_v20240616_9 | 家居、家具与家电 |\n| creator_category_v20240616_19 | 宠物与动物 |\n| creator_category_v20240616_18 | 教育 |\n| creator_category_v20240616_11 | 美食与饮品 |\n| creator_category_v20240616_31 | 汽车与交通 |\n| creator_category_v20240616_5 | 电子产品 |\n| creator_category_v20240616_29 | 游戏 |\n| creator_category_v20240616_30 | 专业服务 |\n| creator_category_v20240616_16 | 母婴 |\n| creator_category_v20240616_33 | 美食与烹饪 |\n| creator_category_v20240616_20 | 旅游与出行 |\n| creator_category_v20240616_27 | 金融与投资 |\n| creator_category_v20240616_2 | 机械与设备 |\n| creator_category_v20240616_21 | 品牌 |\n| creator_category_v20240616_25 | 咨询与服务 |\n| creator_category_v20240616_4 | 房产 |\n| creator_category_v20240616_28 | 政府与政治 |\n| creator_category_v20240616_6 | 餐厅与酒吧 |\n| creator_category_v20240616_26 | IT 与高科技 |\n| creator_category_v20240616_22 | 软件与应用 |\n| creator_category_v20240616_3 | 直播公会 |\n| creator_category_v20240616_7 | 影视与制片 |\n| creator_category_v20240616_34 | 其他 |\n\n\u003e `category`（主播分类）与下方 `product_category`（带货商品分类）是两套不同体系，不要混用。\n\n## 商品分类 ID 参考\n\n`product_category` 参数为直播带货的商品分类 ID：\n\n| 分类 ID | 分类名称 |\n|---------|---------|\n| 601450 | 美妆个护 |\n| 601152 | 女士服装 |\n| 700645 | 保健 |\n| 603014 | 运动与户外 |\n| 601739 | 手机与数码 |\n| 600942 | 家电 |\n| 824328 | 男士服装 |\n| 605248 | 时尚配件 |\n| 700437 | 食品饮料 |\n| 600001 | 居家日用 |\n| 604453 | 家具 |\n| 600024 | 厨房用品 |\n| 600154 | 家纺布艺 |\n| 824584 | 箱包 |\n| 604206 | 玩具和爱好 |\n| 601352 | 鞋靴 |\n| 604579 | 五金工具 |\n| 604968 | 家装建材 |\n| 602118 | 宠物用品 |\n| 601755 | 电脑办公 |\n| 602284 | 母婴用品 |\n| 605196 | 汽车与摩托车 |\n| 951432 | 收藏品 |\n| 801928 | 图书/杂志/影音 |\n| 953224 | 珠宝与衍生品 |\n| 856720 | 二手商品 |\n| 802184 | 儿童时尚 |\n\n\u003e 以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有直播。","name":"数据查询/6.直播数据"},{"name":"数据查询/7.亚马逊数据"},{"name":"文件上传"},{"description":"使用社媒相关功能前，必须先绑定至少一个社媒账号。当前支持 TikTok 两种绑定方式：扫码绑定（「TikTok扫码登录」+「TikTok扫码状态查询」），或授权链接绑定（「获取TikTok授权链接」，将链接发给账号持有人在浏览器打开授权，适合云手机/代运营场景）。TikTok Shop 挂车账号同样支持授权链接绑定（「获取TikTok Shop授权链接」）。\n\n绑定完成后，调用「社媒账号列表」可查看所有已绑定账号及其状态和数据指标。","name":"社媒管理/1.账号管理"},{"description":"通过「上传并发布视频」接口一步完成发布，支持立即发布和定时发布，支持多账号同时发布。\n\n## 前置条件：绑定社媒账号\n\n发布前必须先绑定至少一个社媒账号。前往「社媒管理/1.账号管理」分类，调用「TikTok扫码登录」+「TikTok扫码状态查询」通过扫码绑定。\n\n绑定完成后，通过「社媒账号列表」获取 `id` 字段，即为下方发布接口所需的 `platform_account_id`。\n\n---\n\n## Step 1: 上传文件\n\n### 1.1 调用「生成上传预签名URL」获取临时上传地址（该接口在「文件上传」分类下）\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/upload/presigned-url\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"file_name\": \"my_video.mp4\"}'\n```\n\n返回示例：\n```json\n{\n  \"data\": {\n    \"presigned_url\": \"https://data-datanebula-object.tos-ap-southeast-1.volces.com/upload/my_video.mp4_xxx?...\",\n    \"object_key\": \"upload/my_video.mp4_xxx\",\n    \"s3_bucket\": \"data-datanebula-object\",\n    \"cdn_url\": \"https://oss-data.chuhaijiang.com/upload%2Fmy_video.mp4_xxx?...\"\n  }\n}\n```\n\n\u003e 请记录返回的 `object_key` 和 `s3_bucket`，后续步骤需要用到。\n\n### 1.2 使用 PUT 请求上传文件到 presigned_url\n\n```bash\ncurl -X PUT \"{presigned_url}\" \\\n  -H \"Content-Type: video/mp4\" \\\n  --data-binary @my_video.mp4\n```\n\n\u003e presigned_url 有效期 1 小时，文件大小限制取决于目标平台（TikTok 最大 4GB，YouTube 最大 256GB，Instagram Reels 最大 1GB）。\n\n---\n\n## Step 2: 视频信息校验（推荐）\n\n上传完成后，建议调用「视频信息校验」检查视频是否符合目标平台的规格要求（分辨率、时长、比特率等），避免发布失败：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/videos/check-info\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bucket_name\": \"data-datanebula-object\", \"object_key\": \"upload/my_video.mp4_xxx\"}'\n```\n\n\u003e 该接口会检查视频的编码格式、分辨率、时长等是否满足 TikTok、YouTube、Instagram 等平台的要求。\n\u003e 注意：本接口的文件路径参数名为 `object_key`，与 Step 3 发布接口的 `bucket_key` 不同，两者的值相同（均为 Step 1 返回的 `object_key`）。\n\n---\n\n## Step 3: 调用「上传并发布视频」\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/publish/upload-and-publish\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"video_title\": \"My Video\",\n    \"video_description\": \"Check this out!\",\n    \"bucket_name\": \"data-datanebula-object\",\n    \"bucket_key\": \"upload/my_video.mp4_xxx\",\n    \"publications\": [\n      {\n        \"platform_account_id\": 4687,\n        \"title\": \"Check out this video!\",\n        \"platform_config\": \"{\\\"privacy\\\":\\\"PUBLIC_TO_EVERYONE\\\"}\"\n      }\n    ]\n  }'\n```\n\n\u003e `bucket_name` = Step 1 返回的 `s3_bucket`，`bucket_key` = Step 1 返回的 `object_key`。\n\u003e 支持同时发布到多个账号（publications 数组）。返回的 `session_token` 用于查询发布进度。\n\n### 定时发布\n\n在 publications 中设置 `scheduled_at`（Unix 秒级时间戳），即可定时发布。不同账号可设置不同的发布时间：\n\n```json\n{\n  \"video_title\": \"My Video\",\n  \"bucket_name\": \"data-datanebula-object\",\n  \"bucket_key\": \"upload/my_video.mp4_xxx\",\n  \"publications\": [\n    {\n      \"platform_account_id\": 4687,\n      \"title\": \"Publish now\",\n      \"platform_config\": \"{\\\"privacy\\\":\\\"PUBLIC_TO_EVERYONE\\\"}\"\n    },\n    {\n      \"platform_account_id\": 5678,\n      \"title\": \"Publish tomorrow\",\n      \"scheduled_at\": 1774100400,\n      \"platform_config\": \"{\\\"share_to_feed\\\":true}\"\n    }\n  ]\n}\n```\n\n\u003e `scheduled_at` 需在 5 分钟 ~ 90 天内。不传或为 0 表示立即发布；小于 5 分钟自动降级为立即发布。\n\u003e 已定时的发布可通过「改期」接口修改时间。\n\n---\n\n## Step 4: 调用「发布会话状态」轮询进度\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/publish/session\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"session_token\": \"127169e7-35e3-40...\"}'\n```\n\n\u003e 建议轮询间隔 3~5 秒，重复调用直到状态为完成或失败。\n\n### 取消发布（可选）\n\n- 调用「取消发布会话」取消上传中的会话：`POST /open/v1/social/publish/session/cancel`\n- 调用「取消单个发布」取消已提交的发布：`POST /open/v1/social/publish/cancel`","name":"社媒管理/2.视频发布"},{"name":"社媒管理/3.视频管理"},{"name":"社媒管理/4.评论互动"},{"name":"社媒管理/5.数据分析"},{"name":"社媒管理/6.创作工具"},{"name":"社媒管理/7.TikTok Shop"},{"description":"通过私信接口收发 WhatsApp / WhatsApp Business / LINE / TikTok / Facebook / Instagram 的私信消息，支持文本与图片/视频/文档等媒体消息、引用回复。\n\n## 核心概念\n\n- **渠道（channel）**：绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话\n- **会话（conversation）**：渠道与单个联系人（或群）的对话线程\n- **发送窗口**：部分平台限制商家主动发消息的时间窗——WhatsApp Business / Facebook / Instagram 为客户最后一条消息后 24 小时，TikTok 为 48 小时且最多 10 条，WhatsApp 个人版 / LINE 无限制。窗口外发送会失败\n\n## Step 1: 获取渠道列表\n\n调用「私信渠道列表」查看已绑定的社媒账号，记录 `channel_id`：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/im/channels/list\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 20, \"offset\": 0}'\n```\n\n\u003e `limit` 和 `offset` 必填。默认只返回 active 状态的渠道。\n\n## Step 2: 获取会话列表\n\n用 `channel_id` 调用「私信会话列表」，拿到 `conversation_id` 和发送窗口状态：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/im/conversations/list\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"channel_id\": \"550e8400-e29b-41d4-a716-446655440000\", \"limit\": 20}'\n```\n\n\u003e 列表固定排序：置顶会话在前，其余按最后消息时间倒序。发消息前先检查会话的 `window_info.can_send_message`。\n\n## Step 3: 拉取消息\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/im/conversations/12345/messages\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"limit\": 20}'\n```\n\n\u003e 传 `mark_as_read: true` 会将会话标记为已读并向平台发送已读回执（如 WhatsApp 蓝勾），对方可感知，请按需使用。\n\n## Step 4: 发送消息\n\n文本消息直接发送：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/im/messages/send\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"conversation_id\": \"12345\", \"message_type\": \"text\", \"content\": \"您好，您咨询的商品有货。\"}'\n```\n\n发送图片/视频/文档需先上传文件（三步）：\n\n1. 调用「私信上传预签名 URL」获取上传地址（私信专用存储，与「文件上传」分类下的通用上传接口**不通用**）\n2. 对返回的 `presigned_url` 发起 HTTP PUT 上传文件本体（Content-Type 与申请时一致）\n3. 发送消息时在 `media` 中带上返回的 `object_key` 和 `s3_bucket`：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/social/im/messages/send\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"conversation_id\": \"12345\",\n    \"message_type\": \"image\",\n    \"media\": {\n      \"s3_key\": \"im/2026/07/10/20260710153000_photo.jpg\",\n      \"s3_bucket\": \"datanebula-object\",\n      \"filename\": \"photo.jpg\",\n      \"mime_type\": \"image/jpeg\"\n    }\n  }'\n```\n\n\u003e 发送为同步执行，成功返回 `status: sent`。发送窗口关闭时返回业务错误码 20510；10 秒内向同一会话重复发送相同内容会命中幂等去重。\n\n## 获取新消息\n\n暂不提供消息推送，请通过轮询获取增量消息：先调「私信未读数汇总」检查各渠道未读数，有未读时用「私信会话列表」（`filter_unread: true`）定位会话，再拉取消息列表。\n\n## 更多能力\n\n会话备注（同步为 WhatsApp 联系人显示名）、会话标签计数（按 AI 洞察标签统计）见本分类下对应接口。","name":"社媒管理/8.私信管理"},{"name":"社媒管理/9.店铺经营"},{"description":"查询账户状态、tier 等级与 credits 余额。","name":"账户"}],"x-tagGroups":[{"name":"数据查询","tags":["数据查询/1.商品数据","数据查询/2.达人数据","数据查询/3.视频数据","数据查询/4.店铺数据","数据查询/5.广告与创意情报","数据查询/6.直播数据","数据查询/7.亚马逊数据"]},{"name":"内容制作","tags":["内容制作/1.AI 视频","内容制作/2.AI 图片","内容制作/3.AI 文案","内容制作/4.AI 分析","内容制作/5.AI 画布","内容制作/6.视频编辑"]},{"name":"社媒管理","tags":["社媒管理/1.账号管理","社媒管理/2.视频发布","社媒管理/3.视频管理","社媒管理/4.评论互动","社媒管理/5.数据分析","社媒管理/6.创作工具","社媒管理/7.TikTok Shop","社媒管理/8.私信管理","社媒管理/9.店铺经营"]},{"name":"广告营销","tags":["广告营销/1.广告账户","广告营销/2.常规投放","广告营销/3.GMV MAX"]},{"name":"小匠Agent","tags":["小匠Agent/1.对话","小匠Agent/2.会话与报告"]},{"name":"通用","tags":["异步任务","文件上传","账户"]}]}