{"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":"本次请求后的剩余 credits 余额","type":"number"},"credits_cost":{"description":"本次请求消耗的 credits","type":"number"}},"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| 401 | SOCIAL_AUTH_ERROR | 社媒账号认证失败，请重新授权后重试 |\n| 402 | INSUFFICIENT_CREDITS | credits 余额不足 |\n| 403 | FORBIDDEN_SCOPE | 无权限访问此接口 |\n| 404 | ROUTE_NOT_FOUND | 接口不存在 |\n| 404 | RESOURCE_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","example":"7630899689621032206","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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":{"description":"广告账户列表请求","properties":{"page":{"default":1,"description":"页码，默认 1","minimum":1,"type":"integer"},"page_size":{"default":10,"description":"每页条数，默认 10，最大 100","maximum":100,"minimum":1,"type":"integer"},"platforms":{"description":"平台类型列表；本接口当前仅开放 tiktok-advertiser","items":{"description":"平台类型","enum":["tiktok-advertiser"],"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"accounts":{"description":"OAuth 授权账号列表","items":{"description":"Ads OAuth 授权账号","properties":{"access_token_expires_at":{"description":"Access Token 过期时间，Unix 秒；缺失表示未知或长效","format":"int64","type":"integer"},"account_id":{"description":"Ads OAuth 账号的系统内部 ID；后续请求使用该值","type":"string"},"account_type":{"description":"账号类型","type":"string"},"ads_count":{"description":"该账号下广告数量","format":"int64","type":"integer"},"advertisers":{"description":"该 OAuth token 可访问的广告户列表","items":{"description":"广告户","properties":{"address":{"description":"注册地址","type":"string"},"ads_count":{"description":"广告数量","format":"int64","type":"integer"},"advertiser_account_type":{"description":"广告户类型：RESERVATION 或 AUCTION","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"balance":{"description":"账户余额","type":"number"},"company":{"description":"公司名称","type":"string"},"company_name_editable":{"description":"公司名称是否可编辑","type":"boolean"},"country":{"description":"注册国家或地区 ISO 3166-1 alpha-2 代码","type":"string"},"create_time":{"description":"创建时间，Unix 秒","format":"int64","type":"integer"},"currency":{"description":"ISO 4217 货币代码","type":"string"},"description":{"description":"品牌描述","type":"string"},"display_timezone":{"description":"IANA 时区，如 Asia/Shanghai","type":"string"},"industry":{"description":"行业代码","type":"string"},"language":{"description":"BCP 47 语言代码","type":"string"},"leads_count":{"description":"线索数量","format":"int64","type":"integer"},"name":{"description":"广告户名称","type":"string"},"owner_bc_id":{"description":"广告户所属 Business Center ID","type":"string"},"owner_bc_name":{"description":"所属 Business Center 名称","type":"string"},"rejection_reason":{"description":"审核拒绝原因","type":"string"},"role":{"description":"广告户角色","type":"string"},"status":{"description":"广告户状态","type":"string"},"timezone":{"description":"GMT 偏移时区，如 GMT+08:00","type":"string"}},"required":["advertiser_id","status","role","name","timezone","display_timezone","company","company_name_editable","industry","country","advertiser_account_type","currency","language","balance","create_time"],"type":"object"},"type":"array"},"avatar_url":{"description":"授权账号头像 URL","format":"uri","type":"string"},"bc_name":{"description":"账号级 Business Center 名称","type":"string"},"created_at":{"description":"创建时间，Unix 秒","format":"int64","type":"integer"},"display_name":{"description":"授权账号显示名称","type":"string"},"leads_count":{"description":"该账号下线索数量","format":"int64","type":"integer"},"platform":{"description":"平台类型，TikTok Ads 为 tiktok-advertiser","type":"string"},"platform_account_id":{"description":"该 OAuth 账号的主 advertiser_id，不是 Business Center ID","type":"string"},"remark":{"description":"账号备注","type":"string"},"status":{"description":"OAuth 连接状态：active、expired 或 revoked","type":"string"},"updated_at":{"description":"最近更新时间，Unix 秒","format":"int64","type":"integer"},"username":{"description":"TikTok 用户名","type":"string"}},"required":["account_id","platform","platform_account_id","display_name","username","avatar_url","account_type","status","created_at","updated_at"],"type":"object"},"type":"array"},"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总记录数","format":"int64","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"required":["page","page_size","total_number","total_page"],"type":"object"},"stats":{"description":"账户统计","properties":{"authorized_advertiser_count":{"description":"已授权广告户数量","format":"int64","type":"integer"},"monthly_leads_count":{"description":"本月线索数量","format":"int64","type":"integer"},"total_advertiser_count":{"description":"广告户总数","format":"int64","type":"integer"}},"required":["authorized_advertiser_count","total_advertiser_count","monthly_leads_count"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"list":{"description":"GMV MAX 系列列表","items":{"description":"GMV MAX 系列","properties":{"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"campaign_id":{"description":"GMV MAX 系列 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":"成交额","type":"number"},"modify_time":{"description":"修改时间","type":"string"},"objective_type":{"description":"推广目标","type":"string"},"operation_status":{"description":"用户开关状态","type":"string"},"orders":{"description":"订单数","format":"int64","type":"integer"},"promotion_type":{"description":"推广类型：PRODUCT_GMV_MAX 或 LIVE_GMV_MAX；缓存列表可能缺失","type":"string"},"report_date":{"description":"报表日期","format":"date","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"真实投放状态","type":"string"},"spend":{"description":"消耗金额","type":"number"}},"required":["campaign_id"],"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总记录数","format":"int64","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"required":["page","page_size","total_number","total_page"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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":{"description":"GMV MAX 系列报表请求","properties":{"account_id":{"description":"Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"campaign_ids":{"description":"系列过滤","items":{"description":"系列 ID","type":"string"},"type":"array"},"dimensions":{"description":"聚合维度","items":{"description":"聚合维度","enum":["campaign_id","item_group_id","item_id","stat_time_day"],"type":"string"},"minItems":1,"type":"array"},"end_date":{"description":"统计结束日期 YYYY-MM-DD","format":"date","type":"string"},"gmv_max_promotion_type":{"description":"推广类型","enum":["PRODUCT","LIVE"],"type":"string"},"item_group_ids":{"description":"兼容保留字段：当前 Campaign report 后端不会应用此过滤；请使用 item_group_id 维度","items":{"description":"商品组 ID","type":"string"},"type":"array"},"metrics":{"description":"第一版稳定指标；其他 TikTok 指标组合暂不承诺","items":{"description":"稳定指标","enum":["cost","orders","cost_per_order","gross_revenue","roi"],"type":"string"},"minItems":1,"type":"array"},"page":{"default":1,"description":"页码，默认 1","minimum":1,"type":"integer"},"page_size":{"default":50,"description":"每页条数；后端最大 50，超过会压到 50","maximum":50,"minimum":1,"type":"integer"},"start_date":{"description":"统计开始日期 YYYY-MM-DD","format":"date","type":"string"},"store_ids":{"description":"店铺 ID 真数组；不是 JSON 字符串","items":{"description":"店铺 ID","type":"string"},"minItems":1,"type":"array"}},"required":["account_id","advertiser_id","dimensions","metrics","start_date","end_date","store_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"list":{"description":"GMV MAX 报表行","items":{"description":"GMV MAX 报表行","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"},"average_video_play":{"description":"平均播放时长","type":"string"},"campaign_id":{"description":"维度：系列 ID","type":"string"},"clicks":{"description":"历史兼容字段：点击次数","type":"string"},"cost":{"description":"消耗金额","type":"string"},"cost_per_order":{"description":"单均成本","type":"string"},"creative_delivery_status":{"description":"素材投放状态","type":"string"},"currency":{"description":"货币代码","type":"string"},"delivery_status":{"description":"投放状态","type":"string"},"gross_merchandise_value":{"description":"历史兼容字段；新接入请使用 gross_revenue","type":"string"},"gross_revenue":{"description":"成交额","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"impressions":{"description":"历史兼容字段：展示次数","type":"string"},"item_group_id":{"description":"维度：商品组 ID","type":"string"},"item_id":{"description":"维度：素材或商品 ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_click_rate":{"description":"商品点击率","type":"string"},"product_clicks":{"description":"商品点击数","type":"string"},"product_impressions":{"description":"商品展示数","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"店铺内容类型","type":"string"},"stat_time_day":{"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","format":"uri","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":{"description":"当前页码","type":"integer"},"page_size":{"description":"实际每页条数","type":"integer"},"total":{"description":"总记录数","format":"int64","type":"integer"},"total_pages":{"description":"总页数","type":"integer"}},"required":["base_resp"],"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":"RESOURCE_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":{"description":"GMV MAX 素材报表请求","properties":{"account_id":{"description":"Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"campaign_ids":{"description":"系列过滤；仅传一个 campaign_id 且仅传一个 item_group_id 时才补齐标题、账号和素材来源","items":{"description":"系列 ID","type":"string"},"type":"array"},"end_date":{"description":"统计结束日期 YYYY-MM-DD","format":"date","type":"string"},"gmv_max_promotion_type":{"description":"推广类型","enum":["PRODUCT","LIVE"],"type":"string"},"item_group_ids":{"description":"商品组 ID 真数组","items":{"description":"商品组 ID","type":"string"},"minItems":1,"type":"array"},"page":{"default":1,"description":"页码，默认 1","minimum":1,"type":"integer"},"page_size":{"default":1000,"description":"每页条数；当前后端默认 1000 并原样透传","maximum":1000,"minimum":1,"type":"integer"},"start_date":{"description":"统计开始日期 YYYY-MM-DD","format":"date","type":"string"},"store_ids":{"description":"店铺 ID 真数组","items":{"description":"店铺 ID","type":"string"},"minItems":1,"type":"array"}},"required":["account_id","advertiser_id","start_date","end_date","store_ids","item_group_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"list":{"description":"GMV MAX 素材报表行","items":{"description":"GMV MAX 报表行","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"},"average_video_play":{"description":"平均播放时长","type":"string"},"campaign_id":{"description":"维度：系列 ID","type":"string"},"clicks":{"description":"历史兼容字段：点击次数","type":"string"},"cost":{"description":"消耗金额","type":"string"},"cost_per_order":{"description":"单均成本","type":"string"},"creative_delivery_status":{"description":"素材投放状态","type":"string"},"currency":{"description":"货币代码","type":"string"},"delivery_status":{"description":"投放状态","type":"string"},"gross_merchandise_value":{"description":"历史兼容字段；新接入请使用 gross_revenue","type":"string"},"gross_revenue":{"description":"成交额","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"impressions":{"description":"历史兼容字段：展示次数","type":"string"},"item_group_id":{"description":"维度：商品组 ID","type":"string"},"item_id":{"description":"维度：素材或商品 ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_click_rate":{"description":"商品点击率","type":"string"},"product_clicks":{"description":"商品点击数","type":"string"},"product_impressions":{"description":"商品展示数","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"店铺内容类型","type":"string"},"stat_time_day":{"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","format":"uri","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":{"description":"当前页码","type":"integer"},"page_size":{"description":"实际每页条数","type":"integer"},"total":{"description":"总记录数","format":"int64","type":"integer"},"total_pages":{"description":"总页数","type":"integer"}},"required":["base_resp"],"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":"RESOURCE_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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"store_list":{"description":"GMV MAX 店铺列表","items":{"description":"GMV MAX 店铺","properties":{"account_id":{"description":"店铺所属系统 Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"店铺 GMV MAX 授权所属广告户","type":"string"},"is_gmv_max_available":{"description":"是否可用于 GMV MAX","type":"boolean"},"is_owner_bc":{"description":"是否为所有者 Business Center","type":"boolean"},"store_authorized_bc_id":{"description":"店铺授权的 Business Center ID；GMV MAX 诊断必须原样传回","type":"string"},"store_code":{"description":"店铺编码","type":"string"},"store_id":{"description":"TikTok Shop 店铺 ID","type":"string"},"store_name":{"description":"店铺名称","type":"string"},"store_role":{"description":"店铺角色","type":"string"},"store_status":{"description":"店铺状态","type":"string"},"targeting_region_codes":{"description":"可投放地区","items":{"description":"地区代码","type":"string"},"type":"array"},"thumbnail_signed_url":{"description":"店铺缩略图签名 URL","format":"uri","type":"string"},"thumbnail_url":{"description":"店铺缩略图原始 URL","format":"uri","type":"string"}},"required":["store_id"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"store_products":{"description":"店铺商品列表","items":{"description":"店铺商品","properties":{"currency":{"description":"货币代码","type":"string"},"gmv_max_ads_status":{"description":"GMV MAX 广告状态","type":"string"},"historical_sales":{"description":"历史销量","format":"int64","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":"最低价","type":"string"},"product_image_signed_url":{"description":"商品图片签名 URL","format":"uri","type":"string"},"product_image_url":{"description":"商品图片原始 URL","format":"uri","type":"string"},"product_name":{"description":"商品名称","type":"string"},"status":{"description":"商品可售状态：AVAILABLE 或 NOT_AVAILABLE","type":"string"},"store_id":{"description":"店铺 ID","type":"string"}},"required":["item_group_id"],"type":"object"},"type":"array"},"total":{"description":"总记录数","format":"int64","type":"integer"},"total_pages":{"description":"总页数","type":"integer"}},"required":["base_resp"],"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"last_synced_at":{"description":"本次列表数据最后同步时间，Unix 秒","format":"int64","type":"integer"},"list":{"description":"广告组列表","items":{"description":"广告组","properties":{"adgroup_id":{"description":"TikTok 广告组 ID","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"bid_price":{"description":"出价金额","type":"number"},"bid_type":{"description":"出价策略","type":"string"},"billing_event":{"description":"计费事件","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式","type":"string"},"campaign_id":{"description":"所属推广系列 ID","type":"string"},"campaign_name":{"description":"所属推广系列名称","type":"string"},"clicks":{"description":"点击次数","format":"int64","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","format":"int64","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":"展示次数","format":"int64","type":"integer"},"last_synced_at":{"description":"该广告组最后同步时间，Unix 秒","format":"int64","type":"integer"},"operation_status":{"description":"用户开关状态：ENABLE 或 DISABLE","type":"string"},"optimization_event":{"description":"Pixel 优化事件","type":"string"},"optimization_goal":{"description":"优化目标","type":"string"},"platform_created_at":{"description":"TikTok 平台创建时间，Unix 秒","format":"int64","type":"integer"},"platform_updated_at":{"description":"TikTok 平台更新时间，Unix 秒","format":"int64","type":"integer"},"report_date":{"description":"最近报表日期 YYYY-MM-DD","format":"date","type":"string"},"schedule_end_time":{"description":"投放结束时间，Unix 秒","format":"int64","type":"integer"},"schedule_start_time":{"description":"投放开始时间，Unix 秒","format":"int64","type":"integer"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"spend":{"description":"指定日期范围内消耗","type":"number"}},"required":["adgroup_id"],"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总记录数","format":"int64","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"required":["page","page_size","total_number","total_page"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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":{"description":"广告列表请求","properties":{"account_id":{"description":"Ads OAuth 账号 ID，可由广告账户列表获取","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"end_date":{"description":"指标结束日期 YYYY-MM-DD；必须与 start_date 同时传入","format":"date","type":"string"},"exclude_field_types_in_response":{"description":"排除字段类型，如 NULL_FIELD","items":{"description":"排除字段类型","type":"string"},"type":"array"},"fields":{"description":"指定返回字段","items":{"description":"TikTok 返回字段名","type":"string"},"type":"array"},"filtering":{"description":"广告过滤条件","properties":{"ad_ids":{"description":"广告 ID 列表","items":{"description":"广告 ID","type":"string"},"type":"array"},"adgroup_ids":{"description":"广告组 ID 列表","items":{"description":"广告组 ID","type":"string"},"type":"array"},"buying_types":{"description":"购买类型列表","items":{"description":"购买类型","type":"string"},"type":"array"},"campaign_ids":{"description":"推广系列 ID 列表","items":{"description":"推广系列 ID","type":"string"},"type":"array"},"campaign_system_origins":{"description":"广告系统来源列表","items":{"description":"广告系统来源","type":"string"},"type":"array"},"creation_filter_end_time":{"description":"创建时间终点，YYYY-MM-DD HH:MM:SS UTC","type":"string"},"creation_filter_start_time":{"description":"创建时间起点，YYYY-MM-DD HH:MM:SS UTC","type":"string"},"creative_material_mode":{"description":"创意素材模式","type":"string"},"destination":{"description":"投放目的地","type":"string"},"keyword":{"description":"广告名称模糊搜索关键词","type":"string"},"modified_after":{"description":"仅返回该 UTC 时间后修改的广告","type":"string"},"objective_type":{"description":"推广目标","type":"string"},"optimization_goal":{"description":"优化目标","type":"string"},"primary_status":{"description":"主要状态","type":"string"},"secondary_status":{"description":"次要状态","type":"string"}},"type":"object"},"force_refresh":{"description":"是否强制从 TikTok API 刷新；默认读取本地同步数据","type":"boolean"},"operation_status":{"description":"用户开关状态：ENABLE 或 DISABLE","enum":["ENABLE","DISABLE"],"type":"string"},"page":{"default":1,"description":"页码，默认 1","minimum":1,"type":"integer"},"page_size":{"default":10,"description":"每页条数，默认 10，最大 1000","maximum":1000,"minimum":1,"type":"integer"},"start_date":{"description":"指标开始日期 YYYY-MM-DD；必须与 end_date 同时传入","format":"date","type":"string"},"with_metrics":{"description":"是否返回 Lifetime 指标","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"list":{"description":"广告列表","items":{"description":"广告","properties":{"ad_format":{"description":"广告格式","type":"string"},"ad_id":{"description":"TikTok 广告 ID","type":"string"},"ad_name":{"description":"广告名称","type":"string"},"ad_text":{"description":"广告文案","type":"string"},"ad_texts":{"description":"广告文案列表","items":{"description":"广告文案","type":"string"},"type":"array"},"adgroup_id":{"description":"广告组 ID","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"app_name":{"description":"应用名称","type":"string"},"avatar_icon_web_uri":{"description":"头像 URI","type":"string"},"call_to_action":{"description":"行动号召","type":"string"},"call_to_action_id":{"description":"行动号召 ID","type":"string"},"campaign_id":{"description":"推广系列 ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"campaign_system_origin":{"description":"广告系统来源","type":"string"},"create_time":{"description":"TikTok 创建时间","type":"string"},"creative_authorized":{"description":"创意是否已授权","type":"boolean"},"creative_type":{"description":"创意类型","type":"string"},"currency":{"description":"货币代码","type":"string"},"dark_post_status":{"description":"Push Spark 帖子展示方式：ON=仅广告，OFF=广告及主页","type":"string"},"deeplink":{"description":"深度链接","type":"string"},"deeplink_type":{"description":"深度链接类型","type":"string"},"display_name":{"description":"展示名称","type":"string"},"dynamic_format":{"description":"动态格式","type":"string"},"identity_id":{"description":"身份 ID","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"image_ids":{"description":"图片 ID 列表","items":{"description":"图片 ID","type":"string"},"type":"array"},"images":{"description":"已同步的图片文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"},"is_aco":{"description":"是否为自动化创意优化广告","type":"boolean"},"is_new_structure":{"description":"是否为新结构广告","type":"boolean"},"landing_page_url":{"description":"落地页 URL","format":"uri","type":"string"},"metrics":{"description":"with_metrics=true 时返回的 Lifetime 指标","items":{"description":"广告指标","properties":{"formatted_value":{"description":"格式化指标值","type":"string"},"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"},"metric_value":{"description":"指标数值","type":"number"}},"required":["metric_name","metric_name_cn","metric_value"],"type":"object"},"type":"array"},"modify_time":{"description":"TikTok 修改时间","type":"string"},"music_id":{"description":"音乐 ID","type":"string"},"operation_status":{"description":"用户开关状态：ENABLE、DISABLE 或 FROZEN","type":"string"},"optimization_event":{"description":"优化事件","type":"string"},"page_id":{"description":"页面 ID","format":"int64","type":"integer"},"profile_image_url":{"description":"资料图片 URL","format":"uri","type":"string"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"state":{"description":"统一状态码：1=投放中，2=已停止","type":"integer"},"state_desc":{"description":"统一状态描述","type":"string"},"tiktok_item_id":{"description":"TikTok 帖子 ID","type":"string"},"tracking_app_id":{"description":"追踪应用 ID","type":"string"},"tracking_pixel_id":{"description":"追踪 Pixel ID","format":"int64","type":"integer"},"video_id":{"description":"视频 ID","type":"string"},"videos":{"description":"已同步的视频文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"}},"required":["advertiser_id","campaign_id","adgroup_id","ad_id"],"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总记录数","format":"int64","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"required":["page","page_size","total_number","total_page"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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":{"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_account_id":{"description":"本地广告账号数据库 ID","format":"int64","type":"integer"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"advertiser_name":{"description":"广告户名称","type":"string"},"age_groups":{"description":"年龄段列表","items":{"description":"年龄段枚举","type":"string"},"type":"array"},"age_groups_desc":{"description":"年龄段描述列表","items":{"description":"年龄段中文描述","type":"string"},"type":"array"},"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"bid_price":{"description":"出价金额","type":"number"},"bid_type":{"description":"竞价类型","type":"string"},"bid_type_desc":{"description":"竞价类型中文描述","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式","type":"string"},"budget_mode_desc":{"description":"预算模式中文描述","type":"string"},"campaign_id":{"description":"推广系列 ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"create_time":{"description":"TikTok 创建时间","type":"string"},"currency":{"description":"货币代码","type":"string"},"dark_post_status":{"description":"Push Spark 帖子展示方式：ON=仅广告，OFF=广告及主页","type":"string"},"data_items":{"description":"效果指标列表","items":{"description":"广告详情指标","properties":{"formatted_metric_value":{"description":"格式化指标值","type":"string"},"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"},"metric_value":{"description":"指标数值","type":"number"}},"required":["metric_name","metric_name_cn","metric_value"],"type":"object"},"type":"array"},"gmt_create":{"description":"本地记录创建时间","type":"string"},"gmt_modified":{"description":"本地记录更新时间","type":"string"},"id":{"description":"本地数据库主键","format":"int64","type":"integer"},"images":{"description":"图片文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"},"location_ids":{"description":"定向地区 ID 列表","items":{"description":"地区 ID","type":"string"},"type":"array"},"objective_type":{"description":"推广目标","type":"string"},"objective_type_desc":{"description":"推广目标中文描述","type":"string"},"operation_status":{"description":"用户开关状态","type":"string"},"platform":{"description":"平台类型：2=TikTok","type":"integer"},"platform_desc":{"description":"平台描述","type":"string"},"post_item_id":{"description":"TikTok 帖子 ID","type":"string"},"post_platform":{"description":"帖子平台类型","type":"integer"},"schedule_end_time":{"description":"投放结束时间","type":"string"},"schedule_start_time":{"description":"投放开始时间","type":"string"},"schedule_type":{"description":"排期类型","type":"string"},"schedule_type_desc":{"description":"排期类型中文描述","type":"string"},"secondary_status":{"description":"TikTok 真实投放状态","type":"string"},"state":{"description":"统一状态码","type":"integer"},"state_desc":{"description":"统一状态描述","type":"string"},"videos":{"description":"视频文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"board_items":{"description":"看板汇总指标","items":{"description":"洞察指标","properties":{"formatted_metric_value":{"description":"格式化指标值","type":"string"},"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"},"metric_value":{"description":"指标数值；无数据时可能缺失","type":"number"}},"required":["metric_name","metric_name_cn"],"type":"object"},"type":"array"},"detail_items":{"description":"每日明细","items":{"description":"每日明细","properties":{"date":{"description":"日期 YYYY-MM-DD","format":"date","type":"string"},"items":{"description":"当天指标","items":{"description":"洞察指标","properties":{"formatted_metric_value":{"description":"格式化指标值","type":"string"},"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"},"metric_value":{"description":"指标数值；无数据时可能缺失","type":"number"}},"required":["metric_name","metric_name_cn"],"type":"object"},"type":"array"}},"required":["date","items"],"type":"object"},"type":"array"},"metrics":{"description":"可用指标定义","items":{"description":"指标定义","properties":{"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"}},"required":["metric_name","metric_name_cn"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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/auth-url":{"get":{"description":"为当前 API Key 所属用户生成有效期 60 分钟的 TikTok Business 授权链接，用于跨设备绑定 TikTok 广告账户。\n\n将返回的 `auth_url` 发送给广告账户持有人。对方在链接过期前打开并完成授权后，使用同一响应中的 `ref` 调用「查询 TikTok Ads 绑定结果」接口，轮询至 `status=bound`。\n\n`bound` 表示 OAuth 广告账户已绑定，不表示历史广告数据已经完成同步。授权链接代表将广告账户绑定到当前 API Key 所属用户的权限，请仅发送给可信的账户持有人。","operationId":"ads-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://business-api.tiktok.com/portal/auth?app_id=1234567890\u0026redirect_uri=https%3A%2F%2Fexample.com%2Fcallback\u0026state=ttads-openapi.eyJ1aWQiOiIuLi4ifQ.signature","expires_at":1780003600,"ref":"bind_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUu0"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_url":{"description":"TikTok Business 授权页完整链接。发送给广告账户持有人在任意浏览器打开并完成授权","format":"uri","type":"string"},"expires_at":{"description":"授权链接过期时间，Unix 秒时间戳；链接自签发起 60 分钟内有效","format":"int64","type":"integer"},"ref":{"description":"本次授权的绑定引用。调用查询 TikTok Ads 绑定结果接口时必须原样传入","pattern":"^bind_[A-Za-z0-9_-]{16,128}$","type":"string"}},"required":["auth_url","ref","expires_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":"RESOURCE_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 Business 授权链接","tags":["广告营销/1.广告账户"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.ads.write"}},"/open/v1/ads/tiktok/bind-status":{"post":{"description":"凭获取 TikTok Business 授权链接返回的 ref 查询本次绑定回执。pending 表示尚未产生属于当前 API Key 用户的成功回执；bound 返回本地 account_id 与全部 advertiser_ids。bound 不代表历史广告数据已完成同步。","operationId":"chuhaijiang-ads-tiktok-bind-status","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"ref":{"description":"从 GET /open/v1/ads/tiktok/auth-url 成功响应取得的本次绑定引用；必须原样传入。","pattern":"^bind_[A-Za-z0-9_-]{16,128}$","type":"string"}},"required":["ref"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"status":"pending"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"account":{"description":"仅在 status=bound 时返回。bound 不表示历史广告数据已完成同步。","properties":{"account_id":{"description":"出海匠本地 OAuth Token 账户 ID。","type":"string"},"advertiser_ids":{"description":"本次 OAuth 账户可访问的全部 TikTok 广告户 ID。","items":{"type":"string"},"type":"array"},"display_name":{"type":"string"},"platform":{"enum":["tiktok-advertiser"],"type":"string"},"platform_account_id":{"description":"该 OAuth 账户的主 advertiser_id。","type":"string"}},"required":["account_id","platform","platform_account_id","display_name","advertiser_ids"],"type":"object"},"status":{"description":"本次绑定回执状态。","enum":["pending","bound"],"type":"string"}},"required":["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":"RESOURCE_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 Ads 绑定结果","tags":["广告营销/1.广告账户"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.ads.write"}},"/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":{"schema":{"properties":{"data":{"properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"last_synced_at":{"description":"本次列表数据最后同步时间，Unix 秒","format":"int64","type":"integer"},"list":{"description":"推广系列列表","items":{"description":"推广系列","properties":{"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式","type":"string"},"campaign_id":{"description":"TikTok 推广系列 ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"campaign_type":{"description":"系列类型：REGULAR 或 GMV_MAX","type":"string"},"clicks":{"description":"点击次数","format":"int64","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","format":"int64","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":"展示次数","format":"int64","type":"integer"},"is_cbo":{"description":"是否开启 Campaign Budget Optimization","type":"boolean"},"last_synced_at":{"description":"该系列最后同步时间，Unix 秒","format":"int64","type":"integer"},"objective_type":{"description":"推广目标","type":"string"},"offsite_project_id":{"description":"关联 Amazon 站外 Project ID","format":"int64","type":"integer"},"offsite_project_name":{"description":"关联 Amazon 站外 Project 名称","type":"string"},"operation_status":{"description":"用户开关状态：ENABLE、DISABLE 或 DELETE","type":"string"},"orders":{"description":"订单数","format":"int64","type":"integer"},"platform_created_at":{"description":"TikTok 平台创建时间，Unix 秒","format":"int64","type":"integer"},"platform_updated_at":{"description":"TikTok 平台更新时间，Unix 秒","format":"int64","type":"integer"},"report_date":{"description":"最近报表日期 YYYY-MM-DD","format":"date","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"spend":{"description":"指定日期范围内消耗","type":"number"},"total_onsite_shopping_amount":{"description":"店内购物总金额","type":"number"}},"required":["campaign_id"],"type":"object"},"type":"array"},"page_info":{"description":"分页信息","properties":{"page":{"description":"当前页码","type":"integer"},"page_size":{"description":"每页条数","type":"integer"},"total_number":{"description":"总记录数","format":"int64","type":"integer"},"total_page":{"description":"总页数","type":"integer"}},"required":["page","page_size","total_number","total_page"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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/creation/execute":{"post":{"description":"在 15 分钟有效期内，以确认令牌和幂等键执行已冻结的广告创建意图。同一意图同一幂等键重试返回原结果；部分成功或结果歧义时禁止盲目重试。","operationId":"chuhaijiang-ads-creation-execute","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"广告创建执行请求","properties":{"confirmation_token":{"description":"预检接口仅一次返回的确认令牌","type":"string"},"idempotency_key":{"description":"调用方生成的请求级幂等键；同一意图重试必须复用，最长 128 个字符","maxLength":128,"type":"string"},"prepared_operation_id":{"description":"“预检并冻结广告创建”返回的创建意图 ID","type":"string"}},"required":["prepared_operation_id","confirmation_token","idempotency_key"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"广告创建执行响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"operation_id":{"description":"广告创建操作 ID","type":"string"},"partial_success":{"description":"是否已有部分资源创建成功","type":"boolean"},"reconciliation_required":{"description":"是否需要人工或异步对账；为 true 时禁止自动重试","type":"boolean"},"replayed":{"description":"是否为同一幂等键的结果重放","type":"boolean"},"status":{"description":"整体状态","enum":["prepared","processing","succeeded","partially_succeeded","failed","reconciliation_required","expired"],"type":"string"},"steps":{"description":"创建步骤与资源结果","items":{"additionalProperties":false,"description":"广告创建步骤","properties":{"error_code":{"description":"步骤失败错误码","type":"string"},"error_message":{"description":"步骤失败原因","type":"string"},"name":{"description":"步骤名称","type":"string"},"request_id":{"description":"TikTok 平台请求 ID","type":"string"},"resource_id":{"description":"创建成功后的平台资源 ID","type":"string"},"resource_type":{"description":"创建的资源类型，例如 campaign、adgroup 或 ad","type":"string"},"status":{"description":"步骤状态","enum":["pending","succeeded","failed","ambiguous"],"type":"string"}},"required":["name","status"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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":10,"x-scope":"chuhaijiang.ads.write"}},"/open/v1/ads/tiktok/creation/prepare":{"post":{"description":"校验常规广告或 GMV MAX 创建意图并冻结 15 分钟，返回一次性确认令牌、payload hash、预算预览和确认摘要；本接口不调用 TikTok 写接口。","operationId":"chuhaijiang-ads-creation-prepare","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"广告创建预检请求","oneOf":[{"not":{"required":["gmv_max"]},"properties":{"line":{"enum":["regular"]}},"required":["line","regular"]},{"not":{"required":["regular"]},"properties":{"line":{"enum":["gmv_max"]}},"required":["line","gmv_max"]}],"properties":{"gmv_max":{"additionalProperties":false,"description":"GMV MAX 创建参数","properties":{"accelerate_testing_for_new_videos":{"description":"新视频加速测试配置","type":"string"},"account_id":{"description":"系统内部 Ads OAuth 账号 ID；先调用“广告账户列表”获取","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID；先调用“广告账户列表”获取","type":"string"},"affiliate_posts_enabled":{"description":"是否启用达人帖子","type":"boolean"},"all_products_side_effect_confirmed":{"description":"选择全部商品时的显式确认：确认可能暂停或影响其他广告户中的 VSA/PSA","type":"boolean"},"auto_budget":{"additionalProperties":false,"description":"GMV MAX 自动预算配置","properties":{"auto_budget_cap":{"description":"自动预算上限","type":"number"},"auto_budget_enabled":{"description":"是否开启非推广日自动预算","type":"boolean"},"auto_budget_type":{"description":"自动预算类型","type":"string"},"budget_increase_percentage":{"description":"非推广日预算增幅百分比","type":"integer"},"increase_limit":{"description":"非推广日预算增加次数上限","type":"integer"}},"type":"object"},"budget":{"description":"日预算；币种以广告户币种为准","exclusiveMinimum":true,"minimum":0,"type":"number"},"campaign_name":{"description":"GMV MAX 推广系列名称","type":"string"},"custom_anchor_video_list":{"description":"自定义锚点视频列表","items":{"additionalProperties":false,"description":"GMV MAX 自定义锚点视频","properties":{"campaign_id":{"description":"删除 campaign-level 自定义帖子时使用的 Campaign ID","type":"string"},"identity_info":{"additionalProperties":false,"description":"GMV MAX 认证身份","properties":{"identity_authorized_bc_id":{"description":"身份授权 BC ID","type":"string"},"identity_authorized_shop_id":{"description":"身份授权 Shop ID","type":"string"},"identity_id":{"description":"认证身份 ID","type":"string"},"identity_type":{"description":"认证身份类型","type":"string"},"store_id":{"description":"身份关联店铺 ID","type":"string"}},"required":["identity_id"],"type":"object"},"item_id":{"description":"TikTok 帖子 ID","type":"string"},"spu_id_list":{"description":"链接的 SPU ID 列表","items":{"description":"SPU ID","type":"string"},"type":"array"}},"required":["item_id"],"type":"object"},"type":"array"},"deep_bid_type":{"description":"深度出价类型；当前仅支持 VO_MIN_ROAS","enum":["VO_MIN_ROAS"],"type":"string"},"identity_list":{"description":"认证身份列表","items":{"additionalProperties":false,"description":"GMV MAX 认证身份","properties":{"identity_authorized_bc_id":{"description":"身份授权 BC ID","type":"string"},"identity_authorized_shop_id":{"description":"身份授权 Shop ID","type":"string"},"identity_id":{"description":"认证身份 ID","type":"string"},"identity_type":{"description":"认证身份类型","type":"string"},"store_id":{"description":"身份关联店铺 ID","type":"string"}},"required":["identity_id"],"type":"object"},"type":"array"},"item_group_ids":{"description":"商品组 ID 列表；先调用“店内商品列表”获取","items":{"description":"商品组 ID","type":"string"},"type":"array"},"item_list":{"description":"自定义作品列表","items":{"additionalProperties":false,"description":"GMV MAX 作品与视频","properties":{"identity_info":{"additionalProperties":false,"description":"GMV MAX 认证身份","properties":{"identity_authorized_bc_id":{"description":"身份授权 BC ID","type":"string"},"identity_authorized_shop_id":{"description":"身份授权 Shop ID","type":"string"},"identity_id":{"description":"认证身份 ID","type":"string"},"identity_type":{"description":"认证身份类型","type":"string"},"store_id":{"description":"身份关联店铺 ID","type":"string"}},"required":["identity_id"],"type":"object"},"item_id":{"description":"TikTok 作品 ID","type":"string"},"spu_id_list":{"description":"关联 SPU ID 列表","items":{"description":"SPU ID","type":"string"},"type":"array"},"video_info":{"additionalProperties":false,"description":"GMV MAX 视频引用","properties":{"video_id":{"description":"TikTok 视频 ID","type":"string"}},"required":["video_id"],"type":"object"}},"required":["item_id"],"type":"object"},"type":"array"},"optimization_goal":{"description":"优化目标","type":"string"},"product_specific_type":{"description":"商品选择类型；ALL 表示全部商品","type":"string"},"product_video_specific_type":{"description":"视频选择模式：自动选择或自定义选择","type":"string"},"promotion_days":{"additionalProperties":false,"description":"GMV MAX 推广日配置","properties":{"auto_schedule_enabled":{"description":"是否使用 TikTok Shop promotion days 排期","type":"boolean"},"budget_increase_percentage":{"description":"推广日预算增幅百分比","type":"integer"},"custom_schedule":{"description":"兼容字段：自定义排期列表","items":{"additionalProperties":false,"description":"GMV MAX 自定义排期","properties":{"bid_multiplier":{"description":"出价乘数","type":"number"},"budget_increase_percentage":{"description":"预算增幅百分比","type":"integer"},"end_date":{"description":"结束日期 YYYY-MM-DD","format":"date","type":"string"},"end_time":{"description":"结束时间","type":"string"},"increase_limit":{"description":"单日预算增加次数上限","type":"integer"},"roas_bid_multiplier":{"description":"目标 ROAS 乘数","type":"number"},"start_date":{"description":"开始日期 YYYY-MM-DD","format":"date","type":"string"},"start_time":{"description":"开始时间","type":"string"}},"type":"object"},"type":"array"},"custom_schedule_list":{"description":"官方字段：自定义排期列表","items":{"additionalProperties":false,"description":"GMV MAX 自定义排期","properties":{"bid_multiplier":{"description":"出价乘数","type":"number"},"budget_increase_percentage":{"description":"预算增幅百分比","type":"integer"},"end_date":{"description":"结束日期 YYYY-MM-DD","format":"date","type":"string"},"end_time":{"description":"结束时间","type":"string"},"increase_limit":{"description":"单日预算增加次数上限","type":"integer"},"roas_bid_multiplier":{"description":"目标 ROAS 乘数","type":"number"},"start_date":{"description":"开始日期 YYYY-MM-DD","format":"date","type":"string"},"start_time":{"description":"开始时间","type":"string"}},"type":"object"},"type":"array"},"days":{"description":"推广日期列表","items":{"description":"推广日期","type":"string"},"type":"array"},"increase_limit":{"description":"推广日每日预算增加次数上限","type":"integer"},"is_enabled":{"description":"是否启用推广日","type":"boolean"}},"type":"object"},"roas_bid":{"description":"目标 ROAS，必须大于 0","exclusiveMinimum":true,"minimum":0,"type":"number"},"schedule_end_time":{"description":"排期结束时间","type":"string"},"schedule_start_time":{"description":"排期开始时间","type":"string"},"schedule_type":{"description":"排期类型","type":"string"},"shopping_ads_type":{"description":"购物广告类型，例如 PRODUCT_SHOPPING_ADS","type":"string"},"store_authorized_bc_id":{"description":"店铺授权 BC ID；必须使用“店铺列表”返回值，不可用广告户 owner BC 推断","type":"string"},"store_id":{"description":"TikTok Shop 店铺 ID；先调用“店铺列表”获取","type":"string"}},"required":["account_id","advertiser_id","store_id","store_authorized_bc_id","shopping_ads_type","optimization_goal","deep_bid_type","schedule_type","schedule_start_time","campaign_name","roas_bid"],"type":"object"},"line":{"description":"投放线：regular=常规广告，gmv_max=GMV MAX","enum":["regular","gmv_max"],"type":"string"},"regular":{"additionalProperties":false,"allOf":[{"oneOf":[{"required":["campaign_id"]},{"required":["campaign"]}]},{"oneOf":[{"required":["adgroup_id"]},{"required":["adgroup"]}]}],"description":"常规广告创建意图","properties":{"account_id":{"description":"系统内部 Ads OAuth 账号 ID；先调用“广告账户列表”获取","type":"string"},"adgroup":{"additionalProperties":false,"description":"常规广告组创建参数","properties":{"adgroup_name":{"description":"广告组名称","type":"string"},"age_groups":{"description":"年龄段列表","items":{"description":"年龄段枚举，例如 AGE_18_24","type":"string"},"type":"array"},"bid_price":{"description":"出价金额","exclusiveMinimum":true,"minimum":0,"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":"广告组预算金额；币种以广告户币种为准","exclusiveMinimum":true,"minimum":0,"type":"number"},"budget_mode":{"description":"预算模式","enum":["BUDGET_MODE_DAY","BUDGET_MODE_TOTAL"],"type":"string"},"conversion_bid_price":{"description":"oCPM 转化出价金额","exclusiveMinimum":true,"minimum":0,"type":"number"},"gender":{"description":"性别定向：GENDER_UNLIMITED、GENDER_MALE 或 GENDER_FEMALE","type":"string"},"languages":{"description":"语言代码列表","items":{"description":"TikTok 语言代码","type":"string"},"type":"array"},"location_ids":{"description":"地域 ID 列表；先调用“可投放地域列表”获取","items":{"description":"TikTok 地域 ID","type":"string"},"type":"array"},"operation_status":{"default":"ENABLE","description":"创建后的开关状态","enum":["ENABLE","DISABLE"],"type":"string"},"optimization_event":{"description":"Pixel 优化事件","type":"string"},"optimization_goal":{"description":"优化目标，例如 CLICK、CONVERT、SHOW、REACH","type":"string"},"pacing":{"description":"投放速度，例如 PACING_MODE_SMOOTH 或 PACING_MODE_FAST","type":"string"},"pixel_id":{"description":"TikTok Pixel ID；转化目标使用","type":"string"},"placement_type":{"description":"版位类型，例如 PLACEMENT_TYPE_AUTOMATIC 或 PLACEMENT_TYPE_NORMAL","type":"string"},"placements":{"description":"版位列表","items":{"description":"版位枚举，例如 PLACEMENT_TIKTOK","type":"string"},"type":"array"},"promotion_target_type":{"description":"线索推广目标，例如 INSTANT_PAGE 或 EXTERNAL_WEBSITE","type":"string"},"promotion_type":{"description":"推广对象类型，例如 WEBSITE、APP、LEAD_GENERATION","type":"string"},"schedule_end_time":{"description":"结束时间；schedule_type=SCHEDULE_START_END 时必填，UTC","type":"string"},"schedule_start_time":{"description":"开始时间，格式 YYYY-MM-DD HH:MM:SS，UTC","type":"string"},"schedule_type":{"description":"排期类型","enum":["SCHEDULE_FROM_NOW","SCHEDULE_START_END"],"type":"string"}},"required":["adgroup_name","budget","budget_mode","schedule_type","schedule_start_time","optimization_goal","billing_event"],"type":"object"},"adgroup_id":{"description":"已有 AdGroup ID；与 adgroup 二选一","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID；先调用“广告账户列表”获取","type":"string"},"campaign":{"additionalProperties":false,"description":"常规广告系列创建参数","properties":{"budget":{"description":"推广系列预算金额；币种以广告户币种为准","exclusiveMinimum":true,"minimum":0,"type":"number"},"budget_mode":{"description":"预算模式","enum":["BUDGET_MODE_DAY","BUDGET_MODE_TOTAL"],"type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"objective_type":{"description":"推广目标，例如 TRAFFIC、LEAD_GENERATION、REACH","type":"string"},"operation_status":{"default":"ENABLE","description":"创建后的开关状态","enum":["ENABLE","DISABLE"],"type":"string"},"special_industries":{"description":"特殊行业列表","items":{"description":"特殊行业：HOUSING、EMPLOYMENT 或 CREDIT","type":"string"},"type":"array"}},"required":["campaign_name","objective_type","budget","budget_mode"],"type":"object"},"campaign_id":{"description":"已有 Campaign ID；与 campaign 二选一","type":"string"},"creative":{"additionalProperties":false,"description":"常规广告创意参数","properties":{"ad_format":{"description":"广告格式","enum":["SINGLE_VIDEO","SINGLE_IMAGE","CAROUSEL_ADS","CATALOG_CAROUSEL","LIVE_CONTENT"],"type":"string"},"ad_name":{"description":"广告名称，1-512 个字符","type":"string"},"ad_text":{"description":"广告文案，最长 100 个字符","type":"string"},"aigc_disclosure_type":{"description":"AIGC 素材自披露状态","enum":["SELF_DISCLOSURE","NOT_DECLARED"],"type":"string"},"call_to_action":{"description":"行动号召，例如 LEARN_MORE、SIGN_UP、DOWNLOAD、SHOP_NOW","type":"string"},"carousel_image_ids":{"description":"轮播图片 ID 列表；CAROUSEL_ADS 时必填","items":{"description":"TikTok Ads 图片 ID","type":"string"},"maxItems":35,"type":"array"},"dark_post_status":{"description":"Push Spark Ads 展示方式：ON=仅广告展示，OFF=同时展示在主页","enum":["ON","OFF"],"type":"string"},"display_name":{"description":"广告展示名称","type":"string"},"identity_authorized_bc_id":{"description":"BC 授权 ID；identity_type=BC_AUTH_TT 时必填","type":"string"},"identity_id":{"description":"身份 ID；先调用“广告身份列表”获取","type":"string"},"identity_type":{"description":"身份类型；创建广告时必填","enum":["CUSTOMIZED_USER","AUTH_CODE","TT_USER","BC_AUTH_TT"],"type":"string"},"image_ids":{"description":"图片或视频封面 ID 列表","items":{"description":"TikTok Ads 图片 ID","type":"string"},"maxItems":35,"type":"array"},"landing_page_url":{"description":"落地页 URL","format":"uri","type":"string"},"operation_status":{"default":"ENABLE","description":"创建后的开关状态","enum":["ENABLE","DISABLE"],"type":"string"},"page_id":{"description":"TikTok 即时表单页面 ID；LEAD_GENERATION 目标使用","format":"int64","type":"integer"},"tiktok_item_id":{"description":"TikTok 帖子 ID；TT_USER/BC_AUTH_TT 的 Spark Ads Pull 使用，可由“身份视频列表”获取","type":"string"},"video_id":{"description":"TikTok Ads 素材视频 ID；CUSTOMIZED_USER + SINGLE_VIDEO 时必填","type":"string"}},"required":["ad_name","ad_format","ad_text","identity_type","identity_id"],"type":"object"},"creatives":{"description":"批量创意；非空时优先于 creative，后端单次最多 20 条","items":{"additionalProperties":false,"description":"常规广告创意参数","properties":{"ad_format":{"description":"广告格式","enum":["SINGLE_VIDEO","SINGLE_IMAGE","CAROUSEL_ADS","CATALOG_CAROUSEL","LIVE_CONTENT"],"type":"string"},"ad_name":{"description":"广告名称，1-512 个字符","type":"string"},"ad_text":{"description":"广告文案，最长 100 个字符","type":"string"},"aigc_disclosure_type":{"description":"AIGC 素材自披露状态","enum":["SELF_DISCLOSURE","NOT_DECLARED"],"type":"string"},"call_to_action":{"description":"行动号召，例如 LEARN_MORE、SIGN_UP、DOWNLOAD、SHOP_NOW","type":"string"},"carousel_image_ids":{"description":"轮播图片 ID 列表；CAROUSEL_ADS 时必填","items":{"description":"TikTok Ads 图片 ID","type":"string"},"maxItems":35,"type":"array"},"dark_post_status":{"description":"Push Spark Ads 展示方式：ON=仅广告展示，OFF=同时展示在主页","enum":["ON","OFF"],"type":"string"},"display_name":{"description":"广告展示名称","type":"string"},"identity_authorized_bc_id":{"description":"BC 授权 ID；identity_type=BC_AUTH_TT 时必填","type":"string"},"identity_id":{"description":"身份 ID；先调用“广告身份列表”获取","type":"string"},"identity_type":{"description":"身份类型；创建广告时必填","enum":["CUSTOMIZED_USER","AUTH_CODE","TT_USER","BC_AUTH_TT"],"type":"string"},"image_ids":{"description":"图片或视频封面 ID 列表","items":{"description":"TikTok Ads 图片 ID","type":"string"},"maxItems":35,"type":"array"},"landing_page_url":{"description":"落地页 URL","format":"uri","type":"string"},"operation_status":{"default":"ENABLE","description":"创建后的开关状态","enum":["ENABLE","DISABLE"],"type":"string"},"page_id":{"description":"TikTok 即时表单页面 ID；LEAD_GENERATION 目标使用","format":"int64","type":"integer"},"tiktok_item_id":{"description":"TikTok 帖子 ID；TT_USER/BC_AUTH_TT 的 Spark Ads Pull 使用，可由“身份视频列表”获取","type":"string"},"video_id":{"description":"TikTok Ads 素材视频 ID；CUSTOMIZED_USER + SINGLE_VIDEO 时必填","type":"string"}},"required":["ad_name","ad_format","ad_text","identity_type","identity_id"],"type":"object"},"maxItems":20,"minItems":1,"type":"array"}},"required":["account_id","advertiser_id","creative"],"type":"object"}},"required":["line"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"广告创建预检响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"confirmation_summary":{"description":"供最终用户确认的操作摘要","type":"string"},"confirmation_token":{"description":"仅本次返回的高熵确认令牌；15 分钟内执行时原样提交，服务端不保存明文","type":"string"},"expires_at":{"description":"创建意图过期时间，UTC RFC3339Nano","format":"date-time","type":"string"},"payload_hash":{"description":"冻结业务 payload 的 SHA-256 十六进制摘要","type":"string"},"prepared_operation_id":{"description":"冻结创建意图 ID；执行和查询时使用","type":"string"},"spend_preview":{"additionalProperties":false,"description":"花费预览","properties":{"currency":{"description":"广告户币种；缺失表示后端未返回","type":"string"},"daily_budget":{"description":"可识别的日预算金额","type":"number"}},"type":"object"},"validation":{"additionalProperties":false,"description":"预检结果","properties":{"valid":{"description":"是否通过预检","type":"boolean"},"warnings":{"description":"非阻断警告","items":{"description":"警告说明","type":"string"},"type":"array"}},"required":["valid"],"type":"object"}},"required":["base_resp"],"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":"RESOURCE_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.ads.write"}},"/open/v1/ads/tiktok/diagnosis/snapshot":{"post":{"description":"一次获取已绑定 TikTok 广告户的近实时诊断快照。regular 返回系列、广告组、广告和按日效果；gmv_max 返回店铺授权关系、系列、日报及素材报表。该接口用于诊断和 Agent 输入，不替代完整分页导出；partial=true 时必须检查 steps。开户与绑定请前往出海匠网页完成。","operationId":"chuhaijiang-ads-diagnosis-snapshot","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"广告诊断快照请求","oneOf":[{"properties":{"line":{"enum":["regular"],"type":"string"}}},{"properties":{"line":{"enum":["gmv_max"],"type":"string"}},"required":["store_id","store_authorized_bc_id"]}],"properties":{"account_id":{"description":"Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"end_date":{"description":"诊断结束日期 YYYY-MM-DD；必须与 start_date 同时传入；不传默认今天","format":"date","type":"string"},"line":{"description":"投放线：regular=常规广告，gmv_max=GMV MAX","enum":["regular","gmv_max"],"type":"string"},"start_date":{"description":"诊断开始日期 YYYY-MM-DD；必须与 end_date 同时传入；不传默认最近 7 天","format":"date","type":"string"},"store_authorized_bc_id":{"description":"店铺授权 Business Center ID；line=gmv_max 时必填，必须来自店铺列表","type":"string"},"store_id":{"description":"GMV MAX 店铺 ID；line=gmv_max 时必填","type":"string"}},"required":["line","account_id","advertiser_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"广告诊断快照响应","properties":{"base_resp":{"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"collected_at":{"description":"快照采集完成时间，UTC RFC3339Nano","format":"date-time","type":"string"},"gmv_max":{"description":"GMV MAX 诊断数据","properties":{"advertiser":{"description":"广告户详情","properties":{"advertiser_account_type":{"description":"广告户类型","type":"string"},"advertiser_id":{"description":"广告户 ID","type":"string"},"balance":{"description":"余额","type":"number"},"company":{"description":"公司名称","type":"string"},"country":{"description":"国家或地区","type":"string"},"create_time":{"description":"创建时间","type":"string"},"currency":{"description":"货币代码","type":"string"},"display_timezone":{"description":"IANA 时区","type":"string"},"industry":{"description":"行业代码","type":"string"},"name":{"description":"广告户名称","type":"string"},"role":{"description":"角色","type":"string"},"status":{"description":"状态","type":"string"},"timezone":{"description":"时区","type":"string"}},"type":"object"},"campaign_collected":{"description":"实际采集系列数","format":"int64","type":"integer"},"campaign_total":{"description":"系列总数","format":"int64","type":"integer"},"campaigns":{"description":"GMV MAX 系列","items":{"description":"GMV MAX 系列","properties":{"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"campaign_id":{"description":"GMV MAX 系列 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":"成交额","type":"number"},"modify_time":{"description":"修改时间","type":"string"},"objective_type":{"description":"推广目标","type":"string"},"operation_status":{"description":"用户开关状态","type":"string"},"orders":{"description":"订单数","format":"int64","type":"integer"},"promotion_type":{"description":"推广类型：PRODUCT_GMV_MAX 或 LIVE_GMV_MAX；缓存列表可能缺失","type":"string"},"report_date":{"description":"报表日期","format":"date","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"真实投放状态","type":"string"},"spend":{"description":"消耗金额","type":"number"}},"required":["campaign_id"],"type":"object"},"type":"array"},"creative_coverage":{"description":"素材覆盖率","type":"number"},"creative_report":{"description":"GMV MAX 素材报表","items":{"description":"GMV MAX 报表行","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"},"average_video_play":{"description":"平均播放时长","type":"string"},"campaign_id":{"description":"维度：系列 ID","type":"string"},"clicks":{"description":"历史兼容字段：点击次数","type":"string"},"cost":{"description":"消耗金额","type":"string"},"cost_per_order":{"description":"单均成本","type":"string"},"creative_delivery_status":{"description":"素材投放状态","type":"string"},"currency":{"description":"货币代码","type":"string"},"delivery_status":{"description":"投放状态","type":"string"},"gross_merchandise_value":{"description":"历史兼容字段；新接入请使用 gross_revenue","type":"string"},"gross_revenue":{"description":"成交额","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"impressions":{"description":"历史兼容字段：展示次数","type":"string"},"item_group_id":{"description":"维度：商品组 ID","type":"string"},"item_id":{"description":"维度：素材或商品 ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_click_rate":{"description":"商品点击率","type":"string"},"product_clicks":{"description":"商品点击数","type":"string"},"product_impressions":{"description":"商品展示数","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"店铺内容类型","type":"string"},"stat_time_day":{"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","format":"uri","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"},"daily_report":{"description":"GMV MAX 日报","items":{"description":"GMV MAX 报表行","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"},"average_video_play":{"description":"平均播放时长","type":"string"},"campaign_id":{"description":"维度：系列 ID","type":"string"},"clicks":{"description":"历史兼容字段：点击次数","type":"string"},"cost":{"description":"消耗金额","type":"string"},"cost_per_order":{"description":"单均成本","type":"string"},"creative_delivery_status":{"description":"素材投放状态","type":"string"},"currency":{"description":"货币代码","type":"string"},"delivery_status":{"description":"投放状态","type":"string"},"gross_merchandise_value":{"description":"历史兼容字段；新接入请使用 gross_revenue","type":"string"},"gross_revenue":{"description":"成交额","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"impressions":{"description":"历史兼容字段：展示次数","type":"string"},"item_group_id":{"description":"维度：商品组 ID","type":"string"},"item_id":{"description":"维度：素材或商品 ID","type":"string"},"orders":{"description":"订单数","type":"string"},"product_click_rate":{"description":"商品点击率","type":"string"},"product_clicks":{"description":"商品点击数","type":"string"},"product_impressions":{"description":"商品展示数","type":"string"},"roi":{"description":"ROI","type":"string"},"shop_content_type":{"description":"店铺内容类型","type":"string"},"stat_time_day":{"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","format":"uri","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"},"product_count":{"description":"商品数量","format":"int64","type":"integer"},"selected_store_authorized_bc_id":{"description":"本次选择的店铺授权 Business Center ID","type":"string"},"selected_store_id":{"description":"本次选择的店铺 ID","type":"string"},"stores":{"description":"可访问店铺","items":{"description":"GMV MAX 店铺","properties":{"account_id":{"description":"店铺所属系统 Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"店铺 GMV MAX 授权所属广告户","type":"string"},"is_gmv_max_available":{"description":"是否可用于 GMV MAX","type":"boolean"},"is_owner_bc":{"description":"是否为所有者 Business Center","type":"boolean"},"store_authorized_bc_id":{"description":"店铺授权的 Business Center ID；GMV MAX 诊断必须原样传回","type":"string"},"store_code":{"description":"店铺编码","type":"string"},"store_id":{"description":"TikTok Shop 店铺 ID","type":"string"},"store_name":{"description":"店铺名称","type":"string"},"store_role":{"description":"店铺角色","type":"string"},"store_status":{"description":"店铺状态","type":"string"},"targeting_region_codes":{"description":"可投放地区","items":{"description":"地区代码","type":"string"},"type":"array"},"thumbnail_signed_url":{"description":"店铺缩略图签名 URL","format":"uri","type":"string"},"thumbnail_url":{"description":"店铺缩略图原始 URL","format":"uri","type":"string"}},"required":["store_id"],"type":"object"},"type":"array"},"video_count":{"description":"视频数量","format":"int64","type":"integer"}},"type":"object"},"line":{"description":"实际诊断投放线","enum":["regular","gmv_max"],"type":"string"},"partial":{"description":"是否存在步骤失败或分页截断；true 时必须检查 steps","type":"boolean"},"regular":{"description":"常规广告诊断数据","properties":{"adgroups":{"description":"实时广告组，最多 100 条","items":{"description":"广告组","properties":{"adgroup_id":{"description":"TikTok 广告组 ID","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"bid_price":{"description":"出价金额","type":"number"},"bid_type":{"description":"出价策略","type":"string"},"billing_event":{"description":"计费事件","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式","type":"string"},"campaign_id":{"description":"所属推广系列 ID","type":"string"},"campaign_name":{"description":"所属推广系列名称","type":"string"},"clicks":{"description":"点击次数","format":"int64","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","format":"int64","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":"展示次数","format":"int64","type":"integer"},"last_synced_at":{"description":"该广告组最后同步时间，Unix 秒","format":"int64","type":"integer"},"operation_status":{"description":"用户开关状态：ENABLE 或 DISABLE","type":"string"},"optimization_event":{"description":"Pixel 优化事件","type":"string"},"optimization_goal":{"description":"优化目标","type":"string"},"platform_created_at":{"description":"TikTok 平台创建时间，Unix 秒","format":"int64","type":"integer"},"platform_updated_at":{"description":"TikTok 平台更新时间，Unix 秒","format":"int64","type":"integer"},"report_date":{"description":"最近报表日期 YYYY-MM-DD","format":"date","type":"string"},"schedule_end_time":{"description":"投放结束时间，Unix 秒","format":"int64","type":"integer"},"schedule_start_time":{"description":"投放开始时间，Unix 秒","format":"int64","type":"integer"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"spend":{"description":"指定日期范围内消耗","type":"number"}},"required":["adgroup_id"],"type":"object"},"type":"array"},"ads":{"description":"实时广告，最多 100 条","items":{"description":"广告","properties":{"ad_format":{"description":"广告格式","type":"string"},"ad_id":{"description":"TikTok 广告 ID","type":"string"},"ad_name":{"description":"广告名称","type":"string"},"ad_text":{"description":"广告文案","type":"string"},"ad_texts":{"description":"广告文案列表","items":{"description":"广告文案","type":"string"},"type":"array"},"adgroup_id":{"description":"广告组 ID","type":"string"},"adgroup_name":{"description":"广告组名称","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"app_name":{"description":"应用名称","type":"string"},"avatar_icon_web_uri":{"description":"头像 URI","type":"string"},"call_to_action":{"description":"行动号召","type":"string"},"call_to_action_id":{"description":"行动号召 ID","type":"string"},"campaign_id":{"description":"推广系列 ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"campaign_system_origin":{"description":"广告系统来源","type":"string"},"create_time":{"description":"TikTok 创建时间","type":"string"},"creative_authorized":{"description":"创意是否已授权","type":"boolean"},"creative_type":{"description":"创意类型","type":"string"},"currency":{"description":"货币代码","type":"string"},"dark_post_status":{"description":"Push Spark 帖子展示方式：ON=仅广告，OFF=广告及主页","type":"string"},"deeplink":{"description":"深度链接","type":"string"},"deeplink_type":{"description":"深度链接类型","type":"string"},"display_name":{"description":"展示名称","type":"string"},"dynamic_format":{"description":"动态格式","type":"string"},"identity_id":{"description":"身份 ID","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"image_ids":{"description":"图片 ID 列表","items":{"description":"图片 ID","type":"string"},"type":"array"},"images":{"description":"已同步的图片文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"},"is_aco":{"description":"是否为自动化创意优化广告","type":"boolean"},"is_new_structure":{"description":"是否为新结构广告","type":"boolean"},"landing_page_url":{"description":"落地页 URL","format":"uri","type":"string"},"metrics":{"description":"with_metrics=true 时返回的 Lifetime 指标","items":{"description":"广告指标","properties":{"formatted_value":{"description":"格式化指标值","type":"string"},"metric_name":{"description":"指标英文名","type":"string"},"metric_name_cn":{"description":"指标中文名","type":"string"},"metric_value":{"description":"指标数值","type":"number"}},"required":["metric_name","metric_name_cn","metric_value"],"type":"object"},"type":"array"},"modify_time":{"description":"TikTok 修改时间","type":"string"},"music_id":{"description":"音乐 ID","type":"string"},"operation_status":{"description":"用户开关状态：ENABLE、DISABLE 或 FROZEN","type":"string"},"optimization_event":{"description":"优化事件","type":"string"},"page_id":{"description":"页面 ID","format":"int64","type":"integer"},"profile_image_url":{"description":"资料图片 URL","format":"uri","type":"string"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"state":{"description":"统一状态码：1=投放中，2=已停止","type":"integer"},"state_desc":{"description":"统一状态描述","type":"string"},"tiktok_item_id":{"description":"TikTok 帖子 ID","type":"string"},"tracking_app_id":{"description":"追踪应用 ID","type":"string"},"tracking_pixel_id":{"description":"追踪 Pixel ID","format":"int64","type":"integer"},"video_id":{"description":"视频 ID","type":"string"},"videos":{"description":"已同步的视频文件","items":{"description":"媒体文件","properties":{"format":{"description":"文件格式","type":"string"},"name":{"description":"文件名","type":"string"},"s3_url":{"description":"可访问的签名资源 URL","format":"uri","type":"string"},"type":{"description":"文件类型：image、video 或 file","type":"string"}},"type":"object"},"type":"array"}},"required":["advertiser_id","campaign_id","adgroup_id","ad_id"],"type":"object"},"type":"array"},"campaigns":{"description":"实时推广系列，最多 100 条","items":{"description":"推广系列","properties":{"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"budget":{"description":"预算金额","type":"number"},"budget_mode":{"description":"预算模式","type":"string"},"campaign_id":{"description":"TikTok 推广系列 ID","type":"string"},"campaign_name":{"description":"推广系列名称","type":"string"},"campaign_type":{"description":"系列类型：REGULAR 或 GMV_MAX","type":"string"},"clicks":{"description":"点击次数","format":"int64","type":"integer"},"conversion_rate":{"description":"转化率","type":"number"},"conversions":{"description":"转化次数","format":"int64","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":"展示次数","format":"int64","type":"integer"},"is_cbo":{"description":"是否开启 Campaign Budget Optimization","type":"boolean"},"last_synced_at":{"description":"该系列最后同步时间，Unix 秒","format":"int64","type":"integer"},"objective_type":{"description":"推广目标","type":"string"},"offsite_project_id":{"description":"关联 Amazon 站外 Project ID","format":"int64","type":"integer"},"offsite_project_name":{"description":"关联 Amazon 站外 Project 名称","type":"string"},"operation_status":{"description":"用户开关状态：ENABLE、DISABLE 或 DELETE","type":"string"},"orders":{"description":"订单数","format":"int64","type":"integer"},"platform_created_at":{"description":"TikTok 平台创建时间，Unix 秒","format":"int64","type":"integer"},"platform_updated_at":{"description":"TikTok 平台更新时间，Unix 秒","format":"int64","type":"integer"},"report_date":{"description":"最近报表日期 YYYY-MM-DD","format":"date","type":"string"},"roas":{"description":"完成支付 ROAS","type":"number"},"secondary_status":{"description":"TikTok 真实投放状态；判断是否在投应优先使用该字段","type":"string"},"spend":{"description":"指定日期范围内消耗","type":"number"},"total_onsite_shopping_amount":{"description":"店内购物总金额","type":"number"}},"required":["campaign_id"],"type":"object"},"type":"array"},"report":{"description":"按广告和日期聚合的报表，最多 1000 条","items":{"description":"常规广告报表行","properties":{"dimensions":{"description":"常规广告报表维度","properties":{"ac":{"description":"报表维度 ac","type":"string"},"ad_id":{"description":"报表维度 ad_id","type":"string"},"adgroup_id":{"description":"报表维度 adgroup_id","type":"string"},"advertiser_id":{"description":"报表维度 advertiser_id","type":"string"},"age":{"description":"报表维度 age","type":"string"},"campaign_id":{"description":"报表维度 campaign_id","type":"string"},"contextual_tag":{"description":"报表维度 contextual_tag","type":"string"},"country_code":{"description":"报表维度 country_code","type":"string"},"gender":{"description":"报表维度 gender","type":"string"},"interest_category":{"description":"报表维度 interest_category","type":"string"},"interest_category_v2":{"description":"报表维度 interest_category_v2","type":"string"},"language":{"description":"报表维度 language","type":"string"},"placement":{"description":"报表维度 placement","type":"string"},"platform":{"description":"报表维度 platform","type":"string"},"stat_time_day":{"description":"报表维度 stat_time_day","type":"string"},"stat_time_hour":{"description":"报表维度 stat_time_hour","type":"string"}},"type":"object"},"metrics":{"description":"常规广告报表指标","properties":{"ad_name":{"description":"报表指标 ad_name","type":"string"},"adgroup_name":{"description":"报表指标 adgroup_name","type":"string"},"advertiser_id":{"description":"报表指标 advertiser_id","type":"string"},"average_video_play":{"description":"报表指标 average_video_play","type":"string"},"billed_cost":{"description":"报表指标 billed_cost","type":"string"},"campaign_name":{"description":"报表指标 campaign_name","type":"string"},"clicks":{"description":"报表指标 clicks","type":"string"},"comments":{"description":"报表指标 comments","type":"string"},"conversion_rate":{"description":"报表指标 conversion_rate","type":"string"},"conversions":{"description":"报表指标 conversions","type":"string"},"cost_per_conversion":{"description":"报表指标 cost_per_conversion","type":"string"},"cost_per_onsite_form":{"description":"报表指标 cost_per_onsite_form","type":"string"},"cpc":{"description":"报表指标 cpc","type":"string"},"cpm":{"description":"报表指标 cpm","type":"string"},"cpv":{"description":"报表指标 cpv","type":"string"},"ctr":{"description":"报表指标 ctr","type":"string"},"currency":{"description":"报表指标 currency","type":"string"},"follows":{"description":"报表指标 follows","type":"string"},"impressions":{"description":"报表指标 impressions","type":"string"},"likes":{"description":"报表指标 likes","type":"string"},"onsite_form":{"description":"报表指标 onsite_form","type":"string"},"profile_visits":{"description":"报表指标 profile_visits","type":"string"},"reach":{"description":"报表指标 reach","type":"string"},"shares":{"description":"报表指标 shares","type":"string"},"spend":{"description":"报表指标 spend","type":"string"},"timezone":{"description":"报表指标 timezone","type":"string"},"video_views":{"description":"报表指标 video_views","type":"string"},"video_views_p100":{"description":"报表指标 video_views_p100","type":"string"},"video_views_p25":{"description":"报表指标 video_views_p25","type":"string"},"video_views_p50":{"description":"报表指标 video_views_p50","type":"string"},"video_views_p75":{"description":"报表指标 video_views_p75","type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"total_metrics":{"description":"常规广告汇总指标","properties":{"advertiser_id":{"description":"汇总指标 advertiser_id","type":"string"},"campaign_name":{"description":"汇总指标 campaign_name","type":"string"},"clicks":{"description":"汇总指标 clicks","type":"string"},"currency":{"description":"汇总指标 currency","type":"string"},"impressions":{"description":"汇总指标 impressions","type":"string"},"reach":{"description":"汇总指标 reach","type":"string"},"spend":{"description":"汇总指标 spend","type":"string"},"timezone":{"description":"汇总指标 timezone","type":"string"}},"type":"object"}},"type":"object"},"steps":{"description":"各采集分区状态","items":{"description":"诊断采集步骤","properties":{"count":{"description":"该步骤采集条数","format":"int64","type":"integer"},"duration_ms":{"description":"步骤耗时毫秒","format":"int64","type":"integer"},"error":{"description":"失败或截断原因","type":"string"},"name":{"description":"采集步骤名称","type":"string"},"status":{"description":"步骤状态","enum":["succeeded","failed"],"type":"string"}},"required":["name","status"],"type":"object"},"type":"array"}},"required":["base_resp","line","collected_at","partial"],"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":"RESOURCE_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":15,"x-scope":"chuhaijiang.ads.read"}},"/open/v1/ads/tiktok/identities":{"post":{"description":"发现指定 TikTok 广告户可用于创建广告的身份及其授权能力。账户和广告户需先在出海匠网页完成绑定。","operationId":"chuhaijiang-ads-identities-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"广告身份列表请求","properties":{"account_id":{"description":"系统内部 Ads OAuth 账号 ID；多授权账号场景建议传入","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID；先调用“广告账户列表”获取","type":"string"},"identity_type":{"description":"身份类型","enum":["CUSTOMIZED_USER","AUTH_CODE","TT_USER","BC_AUTH_TT"],"type":"string"}},"required":["advertiser_id","identity_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"广告身份列表响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"list":{"description":"广告身份列表","items":{"additionalProperties":false,"description":"TikTok 广告身份","properties":{"can_access_dm_conversation":{"description":"是否可访问私信会话","type":"boolean"},"can_create_live_ad":{"description":"是否可创建直播广告","type":"boolean"},"can_pull_video":{"description":"是否可以拉取该身份的视频","type":"boolean"},"can_push_video":{"description":"是否可以向该身份推送视频","type":"boolean"},"can_use_video":{"description":"是否可使用该身份的视频创建广告","type":"boolean"},"display_name":{"description":"身份显示名称","type":"string"},"identity_authorized_bc_id":{"description":"BC 授权 ID；identity_type=BC_AUTH_TT 时后续请求必须原样携带","type":"string"},"identity_id":{"description":"身份 ID；创建广告时传入 creative.identity_id","type":"string"},"identity_type":{"description":"身份类型：CUSTOMIZED_USER、AUTH_CODE、TT_USER 或 BC_AUTH_TT","type":"string"},"profile_image":{"description":"身份头像 URL","format":"uri","type":"string"}},"required":["identity_id","identity_type"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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.ads.read"}},"/open/v1/ads/tiktok/identities/videos":{"post":{"description":"按 TikTok 广告身份游标分页获取可用于 Spark Ads 的已有视频和帖子 ID；不负责授权新素材。","operationId":"chuhaijiang-ads-identity-videos-list","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"身份视频列表请求","properties":{"account_id":{"description":"系统内部 Ads OAuth 账号 ID；多授权账号场景建议传入","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"count":{"default":20,"description":"单批数量，默认 20，最大 20","maximum":20,"minimum":1,"type":"integer"},"cursor":{"description":"TikTok 游标；首批不传，后续原样传回响应 cursor","type":"string"},"identity_authorized_bc_id":{"description":"BC 授权 ID；identity_type=BC_AUTH_TT 时必填","type":"string"},"identity_id":{"description":"身份 ID；先调用“广告身份列表”获取","type":"string"},"identity_type":{"description":"身份类型","enum":["TT_USER","BC_AUTH_TT"],"type":"string"},"item_type":{"default":"VIDEO","description":"帖子类型；首版建议 VIDEO","enum":["VIDEO","CAROUSEL"],"type":"string"}},"required":["advertiser_id","identity_type","identity_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"身份视频列表响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"cursor":{"description":"下一批请求使用的 TikTok 游标","type":"string"},"has_more":{"description":"是否还有下一批","type":"boolean"},"list":{"description":"身份视频列表","items":{"additionalProperties":false,"description":"TikTok 身份视频","properties":{"allow_comment":{"description":"是否允许评论","type":"boolean"},"allow_duet":{"description":"是否允许合拍","type":"boolean"},"allow_share":{"description":"是否允许分享","type":"boolean"},"allow_stitch":{"description":"是否允许拼接","type":"boolean"},"caption":{"description":"视频标题或文案","type":"string"},"cover_image_url":{"description":"封面图片 URL","format":"uri","type":"string"},"create_time":{"description":"TikTok 返回的创建时间","type":"string"},"duration":{"description":"视频时长，单位秒","format":"int64","type":"integer"},"height":{"description":"视频高度，单位像素","type":"integer"},"is_ads_authorized":{"description":"是否已授权用于广告","type":"boolean"},"item_id":{"description":"TikTok 帖子 ID；Spark Ads Pull 创建时传入 creative.tiktok_item_id","type":"string"},"item_type":{"description":"帖子类型：VIDEO 或 CAROUSEL","type":"string"},"share_url":{"description":"TikTok 分享链接","format":"uri","type":"string"},"status":{"description":"帖子状态","type":"string"},"video_privacy_status":{"description":"视频隐私状态","type":"string"},"width":{"description":"视频宽度，单位像素","type":"integer"}},"required":["item_id"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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.ads.read"}},"/open/v1/ads/tiktok/identities/videos/detail":{"post":{"description":"校验并获取指定 TikTok 身份下一个或多个帖子的视频详情，用于创建前确认素材可见性和预览。","operationId":"chuhaijiang-ads-identity-video-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"身份视频详情请求","oneOf":[{"required":["item_id"]},{"required":["item_ids"]}],"properties":{"account_id":{"description":"系统内部 Ads OAuth 账号 ID；多授权账号场景建议传入","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"identity_authorized_bc_id":{"description":"BC 授权 ID；BC_AUTH_TT 时必填","type":"string"},"identity_id":{"description":"身份 ID","type":"string"},"identity_type":{"description":"身份类型","type":"string"},"item_id":{"description":"单个 TikTok 帖子 ID；与 item_ids 二选一","type":"string"},"item_ids":{"description":"多个 TikTok 帖子 ID；与 item_id 二选一","items":{"description":"TikTok 帖子 ID","type":"string"},"type":"array"},"item_type":{"description":"帖子类型","enum":["VIDEO","CAROUSEL"],"type":"string"}},"required":["advertiser_id","identity_type","identity_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"身份视频详情响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"video":{"additionalProperties":false,"description":"TikTok 身份视频详情","properties":{"bit_rate":{"description":"视频码率，单位 bps","format":"int64","type":"integer"},"duration":{"description":"视频时长，单位秒","type":"number"},"format":{"description":"视频格式","type":"string"},"height":{"description":"视频高度，单位像素","type":"integer"},"item_id":{"description":"TikTok 帖子 ID；Spark Ads Pull 创建时传入 creative.tiktok_item_id","type":"string"},"item_type":{"description":"帖子类型：VIDEO 或 CAROUSEL","type":"string"},"poster_url":{"description":"视频封面临时 URL","format":"uri","type":"string"},"size":{"description":"视频大小，单位字节","format":"int64","type":"integer"},"status":{"description":"帖子可见状态","type":"string"},"text":{"description":"帖子文案","type":"string"},"video_url":{"description":"视频预览临时 URL","format":"uri","type":"string"},"width":{"description":"视频宽度，单位像素","type":"integer"}},"required":["item_id"],"type":"object"},"videos":{"description":"多个身份视频详情","items":{"additionalProperties":false,"description":"TikTok 身份视频详情","properties":{"bit_rate":{"description":"视频码率，单位 bps","format":"int64","type":"integer"},"duration":{"description":"视频时长，单位秒","type":"number"},"format":{"description":"视频格式","type":"string"},"height":{"description":"视频高度，单位像素","type":"integer"},"item_id":{"description":"TikTok 帖子 ID；Spark Ads Pull 创建时传入 creative.tiktok_item_id","type":"string"},"item_type":{"description":"帖子类型：VIDEO 或 CAROUSEL","type":"string"},"poster_url":{"description":"视频封面临时 URL","format":"uri","type":"string"},"size":{"description":"视频大小，单位字节","format":"int64","type":"integer"},"status":{"description":"帖子可见状态","type":"string"},"text":{"description":"帖子文案","type":"string"},"video_url":{"description":"视频预览临时 URL","format":"uri","type":"string"},"width":{"description":"视频宽度，单位像素","type":"integer"}},"required":["item_id"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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.ads.read"}},"/open/v1/ads/tiktok/operations/detail":{"post":{"description":"在当前团队权限范围内查询受控创建操作及各步骤状态、资源 ID、错误、部分成功与待对账标记。","operationId":"chuhaijiang-ads-operation-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"广告创建操作详情请求","properties":{"operation_id":{"description":"预检或执行返回的广告创建操作 ID","type":"string"}},"required":["operation_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"广告创建操作详情响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"completed_at":{"description":"执行完成时间，UTC RFC3339Nano","format":"date-time","type":"string"},"created_at":{"description":"意图创建时间，UTC RFC3339Nano","format":"date-time","type":"string"},"expires_at":{"description":"意图过期时间，UTC RFC3339Nano","format":"date-time","type":"string"},"line":{"description":"投放线：regular 或 gmv_max","enum":["regular","gmv_max"],"type":"string"},"operation_id":{"description":"广告创建操作 ID","type":"string"},"partial_success":{"description":"是否部分成功","type":"boolean"},"payload_hash":{"description":"冻结业务 payload 的 SHA-256 摘要","type":"string"},"reconciliation_required":{"description":"是否需要人工或异步对账","type":"boolean"},"status":{"description":"整体状态","enum":["prepared","processing","succeeded","partially_succeeded","failed","reconciliation_required","expired"],"type":"string"},"steps":{"description":"创建步骤与资源结果","items":{"additionalProperties":false,"description":"广告创建步骤","properties":{"error_code":{"description":"步骤失败错误码","type":"string"},"error_message":{"description":"步骤失败原因","type":"string"},"name":{"description":"步骤名称","type":"string"},"request_id":{"description":"TikTok 平台请求 ID","type":"string"},"resource_id":{"description":"创建成功后的平台资源 ID","type":"string"},"resource_type":{"description":"创建的资源类型，例如 campaign、adgroup 或 ad","type":"string"},"status":{"description":"步骤状态","enum":["pending","succeeded","failed","ambiguous"],"type":"string"}},"required":["name","status"],"type":"object"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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.ads.write"}},"/open/v1/ads/tiktok/tools/regions":{"post":{"description":"根据广告户、版位和推广目标获取 TikTok 当前可投放地域 ID，供创建新广告组时配置地域定向。","operationId":"chuhaijiang-ads-targeting-regions","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"可投放地域请求","properties":{"account_id":{"description":"系统内部 Ads OAuth 账号 ID","type":"string"},"advertiser_id":{"description":"TikTok 广告户 ID","type":"string"},"brand_safety_partner":{"description":"品牌安全合作伙伴：IAS 或 OPEN_SLATE","type":"string"},"brand_safety_type":{"description":"品牌安全类型","type":"string"},"language":{"default":"en","description":"返回名称语言，默认 en","type":"string"},"level_range":{"default":"ALL","description":"地域层级范围","enum":["ALL","TO_COUNTRY","TO_PROVINCE","TO_CITY","TO_DISTRICT"],"type":"string"},"objective_type":{"description":"推广目标，例如 TRAFFIC、LEAD_GENERATION、REACH","type":"string"},"operating_system":{"description":"操作系统","enum":["ANDROID","IOS"],"type":"string"},"placements":{"description":"投放版位列表","items":{"description":"版位枚举，例如 PLACEMENT_TIKTOK","type":"string"},"minItems":1,"type":"array"},"promotion_target_type":{"description":"线索推广目标类型","type":"string"},"promotion_type":{"description":"推广对象类型","type":"string"},"rf_campaign_type":{"description":"RF 推广系列类型","type":"string"},"shopping_ads_type":{"description":"购物广告类型；PRODUCT_SALES 时使用","type":"string"}},"required":["account_id","advertiser_id","placements","objective_type"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"description":"可投放地域响应","properties":{"base_resp":{"additionalProperties":false,"description":"Ads 后端业务响应","properties":{"code":{"description":"Ads 业务响应码：0 表示成功，非 0 表示业务失败","type":"integer"},"msg":{"description":"Ads 业务响应消息","type":"string"}},"required":["code","msg"],"type":"object"},"region_info":{"description":"地域详细信息","items":{"additionalProperties":false,"description":"TikTok 地域","properties":{"area_type":{"description":"地域类型","type":"string"},"level":{"description":"地域层级","type":"string"},"location_id":{"description":"地域 ID；创建广告组时传入 location_ids","type":"string"},"name":{"description":"地域名称","type":"string"},"next_level_ids":{"description":"下级地域 ID 列表","items":{"description":"下级地域 ID","type":"string"},"type":"array"},"parent_id":{"description":"上级地域 ID","type":"string"},"region_code":{"description":"国家或地区代码","type":"string"},"support_below_18":{"description":"是否支持 18 岁以下投放","type":"boolean"}},"required":["location_id","name"],"type":"object"},"type":"array"},"region_list":{"description":"国家或地区代码列表","items":{"description":"国家或地区代码","type":"string"},"type":"array"}},"required":["base_resp"],"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":"RESOURCE_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.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":"RESOURCE_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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **GPT-Image-2 图片生成** 查看结果。","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":999.9,"credits_cost":6}},"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":"RESOURCE_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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **Nanobanana 图片生成** 查看结果。","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":999.9,"credits_cost":6}},"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":"RESOURCE_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":999.9,"credits_cost":10}},"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":"RESOURCE_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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **SeeDance2.0 Pro Fast视频生成** 查看结果。","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":999.9,"credits_cost":157.5}},"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":"RESOURCE_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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **SeeDance2.0 Pro视频生成** 查看结果。","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":999.9,"credits_cost":195}},"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":"RESOURCE_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/happyhorse/generate":{"post":{"description":"Happy Horse AI 视频生成\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **HappyHorse 1.1 视频生成** 查看结果。","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":999.9,"credits_cost":300}},"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":"RESOURCE_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":"HappyHorse 1.1 视频生成","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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **视频脚本拆解V2** 查看结果。","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":999.9,"credits_cost":10}},"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":"RESOURCE_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/seedance-2.5/generate":{"post":{"description":"Seedance 2.5 AI 视频生成，固定输出 720p，支持 4–29 秒、文生视频、多图参考、参考视频/音频及首尾帧模式。按成功生成的视频时长计费，180 coins/秒。参考素材须为公网可访问 URL；参考音频不能单独使用；首尾帧模式使用 1–2 张图片，且不能与参考视频或参考音频同时使用。\n\n本地素材上传流程：\n1. 调用「文件上传」分类下的「（加速版）生成上传预签名URL」，获取 url 和 signed_url。\n2. 在 180 秒内使用 url 通过 HTTP PUT 上传文件本体。\n3. 上传完成后，将 signed_url 填入 images[].url、reference_videos[].url 或 reference_audios[].url。signed_url 有效期 24 小时，建议上传后立即提交生成任务。\n\n注意：url 仅用于 PUT 上传，不能作为参考素材 URL；os_bucket/os_key 不适用于本接口。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **Seedance 2.5 视频生成** 查看结果。","operationId":"chuhaijiang-ai-seedance-2-5-generate","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"aspect_ratio":{"default":"9:16","description":"输出视频宽高比","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"example":"9:16","type":"string"},"audio":{"default":true,"description":"是否生成背景音乐或声音：true=生成，false=不生成；不传时默认 true","example":false,"type":"boolean"},"duration":{"default":4,"description":"输出视频时长，单位秒；支持 4–29 秒，按 180 coins/秒计费","example":4,"maximum":29,"minimum":4,"type":"integer"},"images":{"description":"参考图片列表，最多 30 张；role_mode=frame 时仅支持 1–2 张","example":[{"url":"https://example.com/reference-image.jpg"}],"items":{"additionalProperties":false,"description":"单个参考图片","properties":{"url":{"description":"公网可访问的参考图片 URL。本地文件请先调用「文件上传」分类下的「（加速版）生成上传预签名URL」，使用返回的 url 通过 HTTP PUT 上传，再将返回的 signed_url 填入本字段","example":"https://example.com/reference-image.jpg","format":"uri","type":"string"}},"required":["url"],"type":"object"},"maxItems":30,"minItems":1,"type":"array"},"language":{"default":"default","description":"生成内容语言代码，例如 zh、en；default 表示不额外翻译提示词","example":"zh","maxLength":10,"type":"string"},"prompt":{"description":"视频生成提示词，1–5000 字符，不能为空","example":"一只橘猫在雨夜的霓虹街道上奔跑，电影感镜头","maxLength":5000,"minLength":1,"type":"string"},"reference_audios":{"description":"参考音频列表，最多 10 个；不能单独使用，须同时提供参考图片或参考视频，且不能与 role_mode=frame 同时使用","example":[{"url":"https://example.com/reference-audio.mp3"}],"items":{"additionalProperties":false,"description":"单个参考音频","properties":{"url":{"description":"公网可访问的参考音频 URL。本地文件请先调用「文件上传」分类下的「（加速版）生成上传预签名URL」，使用返回的 url 通过 HTTP PUT 上传，再将返回的 signed_url 填入本字段","example":"https://example.com/reference-audio.mp3","format":"uri","type":"string"}},"required":["url"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"reference_videos":{"description":"参考视频列表，最多 10 个；不能与 role_mode=frame 同时使用","example":[{"url":"https://example.com/reference-video.mp4"}],"items":{"additionalProperties":false,"description":"单个参考视频","properties":{"url":{"description":"公网可访问的参考视频 URL。本地文件请先调用「文件上传」分类下的「（加速版）生成上传预签名URL」，使用返回的 url 通过 HTTP PUT 上传，再将返回的 signed_url 填入本字段","example":"https://example.com/reference-video.mp4","format":"uri","type":"string"}},"required":["url"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"role_mode":{"default":"reference","description":"图片语义模式：reference=多模态参考图；frame=首帧/首尾帧，此时需提供 1–2 张图片且不能同时提供参考视频或参考音频","enum":["reference","frame"],"example":"reference","type":"string"}},"required":["prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"task_id":"task_abc123"},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":522}},"schema":{"properties":{"data":{"additionalProperties":false,"properties":{"task_id":{"description":"异步任务 ID；调用 GET /open/v1/tasks/{task_id} 查询任务状态和结果","example":"task_abc123","type":"string"}},"required":["task_id"],"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":"RESOURCE_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":"Seedance 2.5 视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":5220,"x-pricing":{"default_quantity":4,"default_tier":"_default","fallback_coin_cost":5220,"mode":"per_unit","quantity_param":"duration","tier_param":"","unit_price_map":{"_default":180}},"x-scope":"chuhaijiang.ai_video.write"}},"/open/v1/ai/videos/selling-points/analyze":{"post":{"description":"聚合分析 TikTok 带货视频，提炼产品卖点、用户痛点、内容呈现方式和热门标签，并返回代表视频基础数据及 TikTok 视频链接。\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **视频卖点可视化分析** 查看结果。","operationId":"chuhaijiang-video-selling-points-analysis","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"卖点可视化分析请求","properties":{"country_code":{"default":"us","description":"TikTok 数据地区代码；不传时默认 us","enum":["us","my","th","vn","mx","de","es","fr","it","br","jp","gb","ph","sg","id"],"example":"us","type":"string"},"field_filter":{"description":"视频筛选条件；可筛选带货视频、赞助视频、发布时间、类目或数值区间","items":{"additionalProperties":false,"description":"单个视频筛选条件","properties":{"filter_key":{"description":"筛选字段标识，例如 video_material_search_product_video、video_material_search_sponsor_video、video_material_search_launch_time 或 video_material_search_category","type":"string"},"left_date_time":{"description":"起始日期，格式 YYYYMMDD；用于发布时间筛选","example":"20260820","pattern":"^[0-9]{8}$","type":"string"},"left_value":{"description":"数值区间下限；仅用于支持数值范围的筛选字段","type":"number"},"quick_option_name":{"description":"快捷选项标识；带货视频使用 video_material_search_product_video_1，赞助视频使用 video_material_search_sponsor_video_1，类目筛选传类目标识","type":"string"},"right_date_time":{"description":"结束日期，格式 YYYYMMDD；用于发布时间筛选","example":"20260827","pattern":"^[0-9]{8}$","type":"string"},"right_value":{"description":"数值区间上限；仅用于支持数值范围的筛选字段","type":"number"}},"required":["filter_key"],"type":"object"},"type":"array"},"keyword":{"description":"待分析的品牌、商品或类目关键词","example":"lipstick","minLength":1,"type":"string"},"keyword_type":{"description":"关键词类型：brand=品牌，product=商品，category=类目；不传时由工作流按通用关键词处理","enum":["brand","product","category"],"example":"product","type":"string"},"language":{"default":"zh","description":"分析结果语言：zh=中文，en=英文；不传时默认 zh","enum":["zh","en"],"example":"zh","type":"string"}},"required":["keyword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"status":"running","task_id":"task_abc123"},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":10}},"schema":{"properties":{"data":{"additionalProperties":false,"properties":{"status":{"description":"任务提交后的初始状态","enum":["running"],"type":"string"},"task_id":{"description":"异步任务 ID；调用 GET /open/v1/tasks/{task_id} 查询状态和结果","example":"task_abc123","type":"string"}},"required":["task_id","status"],"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":"RESOURCE_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.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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **Veo 3.1 视频生成** 查看结果。","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":999.9,"credits_cost":80}},"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":"RESOURCE_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":"Veo 3.1 视频生成","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}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **Wan2.6视频生成** 查看结果。","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":999.9,"credits_cost":150}},"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":"RESOURCE_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/ai/videos/wan30/generate":{"post":{"description":"Wan 3.0 全模态参考视频生成，支持图片、视频和音频参考，支持 2–30 秒、720p/1080p\n\n异步接口，返回 `task_id`。调用 `GET /open/v1/tasks/{task_id}` 查询任务状态和结果。 任务成功后，在任务查询的返回字段中选择 **Wan 3.0 视频生成** 查看结果。","operationId":"chuhaijiang-ai-wan30-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":"视频时长秒数，支持 2–30 之间的任意整数","maximum":30,"minimum":2,"type":"integer"},"images":{"description":"参考图片列表，最多 10 张","items":{"description":"参考素材","properties":{"url":{"description":"可公开访问的图片链接","type":"string"}},"required":["url"],"type":"object"},"maxItems":10,"type":"array"},"language":{"default":"default","description":"语言","type":"string"},"prompt":{"description":"视频生成提示词","type":"string"},"reference_audios":{"description":"参考音频列表，最多 5 个","items":{"description":"参考素材","properties":{"url":{"description":"可公开访问的音频链接","type":"string"}},"required":["url"],"type":"object"},"maxItems":5,"type":"array"},"reference_videos":{"description":"参考视频列表，最多 5 段","items":{"description":"参考素材","properties":{"url":{"description":"可公开访问的视频链接","type":"string"}},"required":["url"],"type":"object"},"maxItems":5,"type":"array"},"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":999.9,"credits_cost":25}},"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":"RESOURCE_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":"Wan 3.0 视频生成","tags":["内容制作/1.AI 视频"],"x-billing-mode":"async_on_complete","x-coin-cost":250,"x-pricing":{"default_quantity":5,"default_tier":"720p","fallback_coin_cost":250,"mode":"per_unit","quantity_param":"duration","tier_param":"resolution","unit_price_map":{"1080p":80,"720p":50}},"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":{"additionalProperties":{"description":"该分组的记录数","type":"integer"},"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":{"additionalProperties":{"description":"该分组的记录数","type":"integer"},"description":"按发布状态分组的计数","type":"object"},"total":{"description":"满足筛选的总条数，可选","type":"integer"},"type_counts":{"additionalProperties":{"description":"该分组的记录数","type":"integer"},"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":"RESOURCE_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":{"additionalProperties":{"description":"该分组的记录数","type":"integer"},"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":"RESOURCE_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":"RESOURCE_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":{"additionalProperties":false,"description":"以乐观锁方式对画布批量应用增量操作的请求","properties":{"canvas_id":{"description":"目标画布 ID","maxLength":128,"minLength":1,"type":"string"},"expected_revision":{"description":"当前画布版本号，从读取画布或上次变更响应获取；不匹配返回 409","minimum":1,"type":"integer"},"operations":{"description":"有序操作列表，按序应用；任一条失败则整批回滚","items":{"description":"单条画布操作；根据 type 选择且仅匹配一个操作分支","oneOf":[{"additionalProperties":false,"description":"重命名画布操作","properties":{"name":{"description":"新的画布名称；去除首尾空白后不能为空，UTF-8 最多 255 字节","maxLength":255,"minLength":1,"type":"string"},"type":{"description":"操作类型","enum":["rename_canvas"],"type":"string"}},"required":["type","name"],"title":"重命名画布","type":"object"},{"additionalProperties":false,"description":"新增节点操作","properties":{"node":{"additionalProperties":false,"description":"完整新节点；不得包含 url、src、asset、generation 等运行时或受保护字段","properties":{"data":{"additionalProperties":true,"description":"节点稳定业务数据；type 必须与 node.type 一致，不得包含运行时 URL、asset 或 generation","properties":{"content":{"description":"文本节点正文；type=text 时使用","type":"string"},"duration":{"description":"视频或音频时长（秒）","minimum":0,"type":"number"},"generationDraft":{"additionalProperties":true,"description":"完整生成配置；字段按 kind 取用","oneOf":[{"properties":{"kind":{"enum":["image"]}},"required":["prompt","model","imageSize","ratio"],"title":"图片生成配置"},{"properties":{"kind":{"enum":["video"]}},"required":["prompt","model","inputMode","aspectRatio","duration","language"],"title":"视频生成配置"},{"properties":{"kind":{"enum":["text"]}},"required":["prompt"],"title":"文本生成配置"},{"properties":{"kind":{"enum":["audio"]}},"required":["text"],"title":"音频生成配置"}],"properties":{"aspectRatio":{"description":"视频宽高比","type":"string"},"candidateCount":{"description":"候选结果数量","minimum":1,"type":"integer"},"duration":{"description":"视频或音频时长，单位秒","minimum":0,"type":"number"},"generateAudio":{"description":"生成视频时是否同时生成音频","type":"boolean"},"imageSize":{"description":"图片输出尺寸","enum":["1K","2K","4K"],"type":"string"},"inputMode":{"description":"视频输入模式","enum":["none","reference","first-frame","first-last-frame"],"type":"string"},"instruction":{"description":"复刻音色补充指令","type":"string"},"instructions":{"description":"系统音色的语气说明","type":"string"},"kind":{"description":"生成内容类型，必须与目标节点类型一致","enum":["image","video","text","audio"],"type":"string"},"language":{"description":"生成语言","type":"string"},"model":{"description":"生成模型标识","type":"string"},"pitch":{"description":"复刻音色色调","type":"number"},"prompt":{"description":"生成提示词；图片、视频和文本生成时使用","type":"string"},"rate":{"description":"复刻音色语速","type":"number"},"ratio":{"description":"图片宽高比","enum":["1:1","3:4","4:3","9:16","16:9"],"type":"string"},"resolution":{"description":"视频分辨率","type":"string"},"responseFormat":{"description":"音频输出格式","enum":["mp3","wav","opus","aac","flac","pcm"],"type":"string"},"sourceType":{"description":"音色来源","enum":["system_voice","voice_profile"],"type":"string"},"speed":{"description":"系统音色语速","type":"number"},"text":{"description":"音频合成文本","type":"string"},"voice":{"description":"系统音色标识","type":"string"},"voiceProfileId":{"description":"复刻音色配置 ID","type":"string"},"volume":{"description":"复刻音色音量","type":"number"}},"required":["kind"],"type":"object"},"height":{"description":"媒体原始高度（像素）","minimum":0,"type":"number"},"label":{"description":"节点显示名称","minLength":1,"type":"string"},"objectFit":{"description":"图片显示方式","enum":["cover","contain"],"type":"string"},"type":{"description":"节点数据类型，必须与 node.type 一致","enum":["image","video","text","audio"],"type":"string"},"width":{"description":"媒体原始宽度（像素）","minimum":0,"type":"number"}},"required":["type","label"],"type":"object"},"id":{"description":"调用方生成的节点唯一 ID","minLength":1,"type":"string"},"position":{"additionalProperties":false,"description":"节点在画布中的坐标","properties":{"x":{"description":"节点横坐标","type":"number"},"y":{"description":"节点纵坐标","type":"number"}},"required":["x","y"],"type":"object"},"type":{"description":"节点类型","enum":["image","video","text","audio"],"type":"string"}},"required":["id","type","position","data"],"type":"object"},"type":{"description":"操作类型","enum":["add_node"],"type":"string"}},"required":["type","node"],"title":"新增节点","type":"object"},{"additionalProperties":false,"description":"更新节点操作","properties":{"node_id":{"description":"目标节点 ID","minLength":1,"type":"string"},"patch":{"additionalProperties":true,"description":"节点局部更新补丁，深合并进现有节点；不得修改 id、type、asset 或 generation 等受保护字段","minProperties":1,"properties":{"data":{"additionalProperties":true,"description":"节点数据补丁；不得包含 type、asset、generation、textGeneration 或 audioGeneration","minProperties":1,"properties":{"content":{"description":"新的文本节点正文","type":"string"},"duration":{"description":"新的视频或音频时长（秒）","minimum":0,"type":"number"},"generationDraft":{"additionalProperties":true,"description":"完整生成配置；字段按 kind 取用","oneOf":[{"properties":{"kind":{"enum":["image"]}},"required":["prompt","model","imageSize","ratio"],"title":"图片生成配置"},{"properties":{"kind":{"enum":["video"]}},"required":["prompt","model","inputMode","aspectRatio","duration","language"],"title":"视频生成配置"},{"properties":{"kind":{"enum":["text"]}},"required":["prompt"],"title":"文本生成配置"},{"properties":{"kind":{"enum":["audio"]}},"required":["text"],"title":"音频生成配置"}],"properties":{"aspectRatio":{"description":"视频宽高比","type":"string"},"candidateCount":{"description":"候选结果数量","minimum":1,"type":"integer"},"duration":{"description":"视频或音频时长，单位秒","minimum":0,"type":"number"},"generateAudio":{"description":"生成视频时是否同时生成音频","type":"boolean"},"imageSize":{"description":"图片输出尺寸","enum":["1K","2K","4K"],"type":"string"},"inputMode":{"description":"视频输入模式","enum":["none","reference","first-frame","first-last-frame"],"type":"string"},"instruction":{"description":"复刻音色补充指令","type":"string"},"instructions":{"description":"系统音色的语气说明","type":"string"},"kind":{"description":"生成内容类型，必须与目标节点类型一致","enum":["image","video","text","audio"],"type":"string"},"language":{"description":"生成语言","type":"string"},"model":{"description":"生成模型标识","type":"string"},"pitch":{"description":"复刻音色色调","type":"number"},"prompt":{"description":"生成提示词；图片、视频和文本生成时使用","type":"string"},"rate":{"description":"复刻音色语速","type":"number"},"ratio":{"description":"图片宽高比","enum":["1:1","3:4","4:3","9:16","16:9"],"type":"string"},"resolution":{"description":"视频分辨率","type":"string"},"responseFormat":{"description":"音频输出格式","enum":["mp3","wav","opus","aac","flac","pcm"],"type":"string"},"sourceType":{"description":"音色来源","enum":["system_voice","voice_profile"],"type":"string"},"speed":{"description":"系统音色语速","type":"number"},"text":{"description":"音频合成文本","type":"string"},"voice":{"description":"系统音色标识","type":"string"},"voiceProfileId":{"description":"复刻音色配置 ID","type":"string"},"volume":{"description":"复刻音色音量","type":"number"}},"required":["kind"],"type":"object"},"height":{"description":"新的媒体原始高度（像素）","minimum":0,"type":"number"},"label":{"description":"新的节点显示名称","minLength":1,"type":"string"},"objectFit":{"description":"新的图片显示方式","enum":["cover","contain"],"type":"string"},"width":{"description":"新的媒体原始宽度（像素）","minimum":0,"type":"number"}},"type":"object"},"position":{"additionalProperties":false,"description":"节点坐标补丁，可只传 x 或 y","minProperties":1,"properties":{"x":{"description":"新的节点横坐标","type":"number"},"y":{"description":"新的节点纵坐标","type":"number"}},"type":"object"}},"type":"object"},"type":{"description":"操作类型","enum":["update_node"],"type":"string"}},"required":["type","node_id","patch"],"title":"更新节点","type":"object"},{"additionalProperties":false,"description":"删除节点操作","properties":{"node_id":{"description":"目标节点 ID；删除节点时会同时清理关联连线","minLength":1,"type":"string"},"type":{"description":"操作类型","enum":["remove_node"],"type":"string"}},"required":["type","node_id"],"title":"删除节点","type":"object"},{"additionalProperties":false,"description":"新增连线操作","properties":{"edge":{"additionalProperties":false,"description":"完整新连线；source 和 target 对应已存在的节点 ID","properties":{"id":{"description":"调用方生成的连线唯一 ID","minLength":1,"type":"string"},"source":{"description":"起点节点 ID","minLength":1,"type":"string"},"sourceHandle":{"description":"起点锚点","enum":["context-source-anchor-left","context-source-anchor-right"],"type":"string"},"target":{"description":"终点节点 ID","minLength":1,"type":"string"},"targetHandle":{"description":"终点锚点","enum":["context-target-anchor-left","context-target-anchor-right"],"type":"string"},"type":{"description":"连线渲染类型","enum":["dashed"],"type":"string"}},"required":["id","source","target"],"type":"object"},"type":{"description":"操作类型","enum":["add_edge"],"type":"string"}},"required":["type","edge"],"title":"新增连线","type":"object"},{"additionalProperties":false,"description":"删除连线操作","properties":{"edge_id":{"description":"目标连线 ID","minLength":1,"type":"string"},"type":{"description":"操作类型","enum":["remove_edge"],"type":"string"}},"required":["type","edge_id"],"title":"删除连线","type":"object"},{"additionalProperties":false,"description":"挂载素材操作","properties":{"asset":{"additionalProperties":false,"description":"绑定到节点的稳定素材引用，不得包含 URL、File、blob 或 data URI","properties":{"duration":{"description":"视频或音频时长（秒）","minimum":0,"type":"number"},"height":{"description":"素材高度（像素）","minimum":0,"type":"number"},"mediaType":{"description":"素材媒体类型，必须与节点类型一致","enum":["image","video","audio"],"type":"string"},"origin":{"description":"素材来源场景","enum":["generation","upload","library"],"type":"string"},"source":{"description":"稳定素材来源；oss 使用存储坐标，task 使用本人生成任务","oneOf":[{"additionalProperties":false,"properties":{"kind":{"description":"素材来源类型","enum":["oss"],"type":"string"},"osBucket":{"description":"对象存储 Bucket","minLength":1,"type":"string"},"osKey":{"description":"对象存储 Key","minLength":1,"type":"string"},"sourceTaskId":{"description":"可选的来源生成任务 ID","minLength":1,"type":"string"}},"required":["kind","osBucket","osKey"],"title":"OSS 稳定素材","type":"object"},{"additionalProperties":false,"properties":{"kind":{"description":"素材来源类型","enum":["task"],"type":"string"},"osBucket":{"description":"任务产物的对象存储 Bucket；与 osKey 成对传入","minLength":1,"type":"string"},"osKey":{"description":"任务产物的对象存储 Key；与 osBucket 成对传入","minLength":1,"type":"string"},"sourceTaskId":{"description":"本人生成任务 ID","minLength":1,"type":"string"}},"required":["kind","sourceTaskId"],"title":"生成任务素材","type":"object"}]},"width":{"description":"素材宽度（像素）","minimum":0,"type":"number"}},"required":["mediaType","source"],"type":"object"},"node_id":{"description":"目标节点 ID","minLength":1,"type":"string"},"type":{"description":"操作类型","enum":["attach_asset"],"type":"string"}},"required":["type","node_id","asset"],"title":"挂载素材","type":"object"},{"additionalProperties":false,"description":"解绑素材操作","properties":{"node_id":{"description":"目标节点 ID","minLength":1,"type":"string"},"type":{"description":"操作类型","enum":["detach_asset"],"type":"string"}},"required":["type","node_id"],"title":"解绑素材","type":"object"},{"additionalProperties":false,"description":"绑定生成任务操作","properties":{"node_id":{"description":"目标节点 ID","minLength":1,"type":"string"},"task":{"additionalProperties":false,"description":"要绑定到节点的生成任务；toolName 必须与节点类型匹配","properties":{"attemptId":{"description":"生成尝试 ID","type":"string"},"config":{"additionalProperties":true,"description":"完整生成配置；字段按 kind 取用","oneOf":[{"properties":{"kind":{"enum":["image"]}},"required":["prompt","model","imageSize","ratio"],"title":"图片生成配置"},{"properties":{"kind":{"enum":["video"]}},"required":["prompt","model","inputMode","aspectRatio","duration","language"],"title":"视频生成配置"},{"properties":{"kind":{"enum":["text"]}},"required":["prompt"],"title":"文本生成配置"},{"properties":{"kind":{"enum":["audio"]}},"required":["text"],"title":"音频生成配置"}],"properties":{"aspectRatio":{"description":"视频宽高比","type":"string"},"candidateCount":{"description":"候选结果数量","minimum":1,"type":"integer"},"duration":{"description":"视频或音频时长，单位秒","minimum":0,"type":"number"},"generateAudio":{"description":"生成视频时是否同时生成音频","type":"boolean"},"imageSize":{"description":"图片输出尺寸","enum":["1K","2K","4K"],"type":"string"},"inputMode":{"description":"视频输入模式","enum":["none","reference","first-frame","first-last-frame"],"type":"string"},"instruction":{"description":"复刻音色补充指令","type":"string"},"instructions":{"description":"系统音色的语气说明","type":"string"},"kind":{"description":"生成内容类型，必须与目标节点类型一致","enum":["image","video","text","audio"],"type":"string"},"language":{"description":"生成语言","type":"string"},"model":{"description":"生成模型标识","type":"string"},"pitch":{"description":"复刻音色色调","type":"number"},"prompt":{"description":"生成提示词；图片、视频和文本生成时使用","type":"string"},"rate":{"description":"复刻音色语速","type":"number"},"ratio":{"description":"图片宽高比","enum":["1:1","3:4","4:3","9:16","16:9"],"type":"string"},"resolution":{"description":"视频分辨率","type":"string"},"responseFormat":{"description":"音频输出格式","enum":["mp3","wav","opus","aac","flac","pcm"],"type":"string"},"sourceType":{"description":"音色来源","enum":["system_voice","voice_profile"],"type":"string"},"speed":{"description":"系统音色语速","type":"number"},"text":{"description":"音频合成文本","type":"string"},"voice":{"description":"系统音色标识","type":"string"},"voiceProfileId":{"description":"复刻音色配置 ID","type":"string"},"volume":{"description":"复刻音色音量","type":"number"}},"required":["kind"],"type":"object"},"createdAt":{"description":"任务创建时间，建议使用 RFC 3339 格式","type":"string"},"inputs":{"description":"生成任务输入素材，最多 20 个","items":{"additionalProperties":false,"description":"生成任务使用的稳定输入素材","properties":{"duration":{"description":"输入视频或音频时长（秒）","minimum":0,"type":"number"},"mediaType":{"description":"输入素材类型","enum":["image","video","audio"],"type":"string"},"osBucket":{"description":"对象存储 Bucket","minLength":1,"type":"string"},"osKey":{"description":"对象存储 Key","minLength":1,"type":"string"},"role":{"description":"输入素材角色","enum":["reference-image","first-frame","last-frame","reference-video","reference-audio"],"type":"string"},"sourceLabel":{"description":"来源节点显示名称","type":"string"},"sourceNodeId":{"description":"来源画布节点 ID","type":"string"},"sourceTaskId":{"description":"可选的来源生成任务 ID","minLength":1,"type":"string"}},"required":["osBucket","osKey"],"type":"object"},"maxItems":20,"type":"array"},"instruction":{"description":"文本生成指令","type":"string"},"sessionId":{"description":"生成会话 ID","type":"string"},"status":{"description":"任务状态；submitting 会由服务端归一化为 pending","enum":["submitting","pending","running"],"type":"string"},"taskId":{"description":"本人生成任务 ID；不得包含 /、? 或 #","maxLength":255,"minLength":1,"pattern":"^[^/?#]+$","type":"string"},"toolName":{"description":"生成工具名称","enum":["submit_image_generation","submit_product_video","submit_audio_tts","submit_canvas_audio_tts","submit_canvas_text"],"type":"string"}},"required":["taskId","toolName","status"],"type":"object"},"type":{"description":"操作类型","enum":["bind_generation_task"],"type":"string"}},"required":["type","node_id","task"],"title":"绑定生成任务","type":"object"},{"additionalProperties":false,"description":"设置视口操作","properties":{"type":{"description":"操作类型","enum":["set_viewport"],"type":"string"},"value":{"additionalProperties":false,"description":"画布视口","properties":{"x":{"description":"视口横向偏移","type":"number"},"y":{"description":"视口纵向偏移","type":"number"},"zoom":{"description":"缩放比例，必须大于 0","exclusiveMinimum":true,"minimum":0,"type":"number"}},"required":["x","y","zoom"],"type":"object"}},"required":["type","value"],"title":"设置视口","type":"object"}]},"maxItems":200,"minItems":1,"type":"array"},"source_client_id":{"description":"调用方客户端标识；用于 WebSocket 变更事件回声去重，不影响业务结果","maxLength":128,"minLength":1,"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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"〔视频〕画幅比例。sd25_official 支持 9:16 / 16:9 / 1:1 / 4:3 / 3:4 / 21:9；其他模型可选值随模型能力而定","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"example":"16:9","type":"string"},"duration":{"description":"〔视频〕时长（秒），范围随模型而定：Seedance 2.0 系为 5–15 秒，sd25_pro 为 4–29 秒，sd25_official 为 4–30 秒；其他模型按各自能力。视频费用 = 模型×分辨率每秒单价 × duration","example":10,"type":"integer"},"generateAudio":{"description":"〔视频·仅 sd25_official〕是否生成音频，可选：true=生成，false=不生成；其他模型不支持此字段","example":false,"type":"boolean"},"imageSize":{"description":"〔图片〕清晰度：1K / 2K / 4K，图片生成的计费依据","type":"string"},"inputMode":{"description":"〔视频〕参考素材使用方式：none / reference（全能参考）/ first-frame（首帧）/ first-last-frame（首尾帧）。不传时服务端按模型与上下文素材自动推导。sd25_official 严格校验：none 不能包含素材；reference 最多 30 张图片、10 个视频、10 个音频且总数不超过 50；first-frame 必须恰好 1 张图片；first-last-frame 必须恰好 2 张图片","enum":["none","reference","first-frame","first-last-frame"],"example":"reference","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（Nanobanana）/ gpt_image_2（GPT Image 2）；视频：sd25_official（Seedance 2.5 官方版）/ sd25_pro（Seedance 2.5 Pro 渠道版）/ sd_pro（Seedance 2.0 Pro）/ happyhorse（HappyHorse 1.1）/ sd_pro_fast（Seedance 2.0 Fast）/ sd_pro_mini（Seedance 2.0 Mini）/ veo31（Veo 3.1）/ wan26（Wan 2.6）。视频模型列表与当前画布前端可见且本接口可调用的模型保持一致","example":"sd25_official","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":"〔视频〕目标输出分辨率。sd25_official 必须显式传入 720p / 1080p / 2k / 4k，这四档均由 480p 母版超分生成；对外不支持 480p。其他模型可选值随模型能力而定，影响每秒单价","enum":["720p","1080p","2k","4k"],"example":"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 由一跳上下文自动推导。使用 sd25_official 时，服务端最终组装出的 prompt 必须非空，参考素材不能替代 prompt；audio 节点时本字段作为合成台词文本","example":"让产品在电影感光影中缓慢旋转，突出材质细节","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 为错误信息","properties":{"code":{"description":"业务状态码，0 表示成功；非 0 为业务错误码，如参数校验失败、乐观锁冲突（409）、权限不足（403）等","type":"integer"},"msg":{"description":"状态描述，成功为 \"success\"，失败为具体错误原因","type":"string"}},"type":"object"},"current_revision":{"description":"发生 409 版本冲突时返回的当前画布版本号","type":"integer"},"document":{"description":"生成提交并绑定后的画布文档完整记录（含 payload 与新 revision），后续写操作以其中 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 / 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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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 等）","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"},"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":"RESOURCE_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":{"additionalProperties":{"description":"可访问的素材签名 URL","format":"uri","type":"string"},"description":"素材运行时签名 URL 映射，key 为节点 ID（无则为 bucket/key），value 为可直接访问的预签名 URL；仅运行时使用","type":"object"},"created_at":{"description":"分享创建时间（RFC3339），可能省略","type":"string"},"name":{"description":"画布名称","type":"string"},"snapshot":{"description":"已脱敏的画布快照，去除了 ownerKey 及所有运行时 URL 字段","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"},"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"},"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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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","example":"7432715061908507950","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":"包含关联资源，逗号分隔（可选值: analysis(分析数据), embedding(向量数据)）","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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"达人机构榜结果列表","items":{"properties":{"avg_commission_rate":{"description":"平均佣金率，原始比值","nullable":true,"type":"number"},"follower_count":{"description":"粉丝数","nullable":true,"type":"number"},"has_email_address":{"description":"是否有公开联系邮箱","nullable":true,"type":"boolean"},"has_phone":{"description":"是否有公开联系电话","nullable":true,"type":"boolean"},"has_whats_app":{"description":"是否有 WhatsApp 联系方式","nullable":true,"type":"boolean"},"id":{"description":"榜单实体唯一标识","type":"string"},"partner_icon":{"description":"机构图标","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"partner_id":{"description":"机构 ID","nullable":true,"type":"string"},"partner_name":{"description":"机构名称","nullable":true,"type":"string"},"partner_top3_category":{"description":"机构带货品类及排名","items":{"properties":{"product_category_label":{"description":"商品品类 ID","type":"string"},"ranking":{"description":"该品类排名","type":"number"}},"type":"object"},"nullable":true,"type":"array"},"partner_top3_category_list":{"description":"机构排名前三的带货品类 ID 列表","items":{"type":"string"},"nullable":true,"type":"array"},"total_30d_video_live_gmv":{"description":"近 30 天视频与直播带货销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"total_30d_video_live_sold_count":{"description":"近 30 天视频与直播带货销量","nullable":true,"type":"number"},"total_related_creator_count":{"description":"关联达人数","nullable":true,"type":"number"},"total_related_product_count":{"description":"关联商品总数","nullable":true,"type":"number"},"total_related_seller_count":{"description":"关联店铺总数","nullable":true,"type":"number"},"video_count":{"description":"视频数","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"带货达人榜结果列表","items":{"properties":{"bio_email":{"description":"简介邮箱","nullable":true,"type":"string"},"category_label":{"description":"达人内容品类标识","nullable":true,"type":"string"},"channel_id":{"description":"YouTube 频道地址","nullable":true,"type":"string"},"country_code":{"description":"国家或地区代码","nullable":true,"type":"string"},"creator_oecuid":{"description":"TikTok 电商达人标识","nullable":true,"type":"string"},"facebook_url":{"description":"Facebook链接","nullable":true,"type":"string"},"follower_count":{"description":"粉丝数","nullable":true,"type":"number"},"handle":{"description":"TikTok用户名","nullable":true,"type":"string"},"id":{"description":"榜单实体唯一标识","type":"string"},"ins_id":{"description":"Instagram账号","nullable":true,"type":"string"},"interval_ecom_video_play_count_growth":{"description":"统计周期带货视频新增播放量","nullable":true,"type":"number"},"interval_live_user":{"description":"统计周期直播观看人数","nullable":true,"type":"number"},"interval_new_follower":{"description":"统计周期新增粉丝数","nullable":true,"type":"number"},"l1_category_aggregated_live_gmv":{"description":"所选一级品类的直播带货销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"l1_category_aggregated_total_gmv":{"description":"所选一级品类的总销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"l1_category_aggregated_video_gmv":{"description":"所选一级品类的视频带货销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"linkedin_url":{"description":"LinkedIn链接","nullable":true,"type":"string"},"nickname":{"description":"昵称","nullable":true,"type":"string"},"product_category_label_list":{"description":"达人带货品类 ID 列表","items":{"type":"string"},"nullable":true,"type":"array"},"product_count":{"description":"商品数量","nullable":true,"type":"number"},"telegram_url":{"description":"Telegram 联系地址","nullable":true,"type":"string"},"titkok_creator_commercial_interval_live_gmv":{"description":"统计周期直播带货销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"titkok_creator_commercial_interval_total_video_live_gmv":{"description":"统计周期视频与直播带货总销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"titkok_creator_commercial_interval_video_gmv":{"description":"统计周期视频带货销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"twitter_id":{"description":"Twitter/X账号","nullable":true,"type":"string"},"uid":{"description":"达人用户 ID","nullable":true,"type":"string"},"unique_id":{"description":"TikTok用户名","nullable":true,"type":"string"},"user_avatar":{"description":"用户头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"user_sell_product_l1_category":{"description":"达人带货商品一级品类 ID 列表","items":{"type":"string"},"nullable":true,"type":"array"},"whatsapp_url":{"description":"WhatsApp链接","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"达人涨粉榜结果列表","items":{"properties":{"bio_email":{"description":"简介邮箱","nullable":true,"type":"string"},"category_label":{"description":"达人内容品类标识","nullable":true,"type":"string"},"channel_id":{"description":"YouTube 频道地址","nullable":true,"type":"string"},"creator_oecuid":{"description":"TikTok 电商达人标识","nullable":true,"type":"string"},"facebook_url":{"description":"Facebook链接","nullable":true,"type":"string"},"follower_count":{"description":"粉丝数","nullable":true,"type":"number"},"handle":{"description":"TikTok用户名","nullable":true,"type":"string"},"id":{"description":"榜单实体唯一标识","type":"string"},"ins_id":{"description":"Instagram账号","nullable":true,"type":"string"},"interval_new_follower":{"description":"统计周期新增粉丝数","nullable":true,"type":"number"},"linkedin_url":{"description":"LinkedIn链接","nullable":true,"type":"string"},"nickname":{"description":"昵称","nullable":true,"type":"string"},"product_category_label_list":{"description":"达人带货品类 ID 列表","items":{"type":"string"},"nullable":true,"type":"array"},"telegram_url":{"description":"Telegram 联系地址","nullable":true,"type":"string"},"tioktok_creator_growth_interval_new_follower_ratio":{"description":"统计周期粉丝增长率，原始比值","nullable":true,"type":"number"},"twitter_id":{"description":"Twitter/X账号","nullable":true,"type":"string"},"uid":{"description":"达人用户 ID","nullable":true,"type":"string"},"unique_id":{"description":"TikTok用户名","nullable":true,"type":"string"},"user_avatar":{"description":"用户头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"user_sell_product_l1_category":{"description":"达人带货商品一级品类 ID 列表","items":{"type":"string"},"nullable":true,"type":"array"},"video_count":{"description":"视频数","nullable":true,"type":"number"},"whatsapp_url":{"description":"WhatsApp链接","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"热力图容器","items":{"properties":{"graph":{"description":"品类热力图树","items":{"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":{"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"},"parent_category":{"description":"父品类 ID","type":"string"}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.4}},"schema":{"properties":{"data":{"properties":{"filter_list":{"description":"品类销售额分布","items":{"properties":{"filter_key":{"description":"筛选字段键","type":"string"},"filter_type":{"description":"筛选类型标识","type":"string"},"quick_option_list":{"description":"品类列表","items":{"properties":{"children":{"description":"子品类列表","items":{"properties":{"children":{"description":"子品类列表","items":{"properties":{"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"},"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"},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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","example":"7636861069956221727","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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":{"example":{"asin":"B0CP9YB3Q4","marketplace":"us"},"properties":{"asin":{"description":"Amazon 商品 ID（ASIN，10 位大写字母或数字，如 B0CP9YB3Q4），可从「Amazon 商品搜索」接口（数据查询/7.亚马逊数据 分组）的返回结果中获取","example":"B0CP9YB3Q4","maxLength":10,"minLength":10,"pattern":"^[A-Z0-9]{10}$","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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":{"example":{"asin":"B0CP9YB3Q4","marketplace":"us"},"properties":{"asin":{"description":"Amazon 商品唯一标识（ASIN，10 位大写字母或数字，如 B0CP9YB3Q4），从「Amazon 商品搜索」接口（数据查询/7.亚马逊数据 分组）的返回中获取","example":"B0CP9YB3Q4","maxLength":10,"minLength":10,"pattern":"^[A-Z0-9]{10}$","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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":{"example":{"keyword":"tumbler","marketplace":"us","page":1},"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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"商品热推榜商品列表","items":{"properties":{"biz_type":{"description":"商家业务类型代码","nullable":true,"type":"number"},"ceiling_price":{"description":"最高价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","nullable":true,"type":"number"},"country_code":{"description":"国家或地区代码","nullable":true,"type":"string"},"floor_price":{"description":"最低价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"id":{"description":"榜单实体唯一标识","type":"string"},"interval_gmv":{"description":"统计周期销售额","nullable":true,"type":"number"},"interval_live_count":{"description":"统计周期关联直播数","nullable":true,"type":"number"},"interval_live_user":{"description":"统计周期直播观看人数","nullable":true,"type":"number"},"interval_related_creator_count":{"description":"统计周期关联达人数","nullable":true,"type":"number"},"interval_sold_count":{"description":"统计周期销量","nullable":true,"type":"number"},"interval_video_play_count":{"description":"统计周期关联视频播放量","nullable":true,"type":"number"},"l1_category":{"description":"一级类目","nullable":true,"type":"string"},"l2_category":{"description":"二级类目","nullable":true,"type":"string"},"l3_category":{"description":"三级类目","nullable":true,"type":"string"},"product_id":{"description":"商品ID","nullable":true,"type":"string"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"nullable":true,"type":"array"},"product_name":{"description":"商品名称","nullable":true,"type":"string"},"product_rating":{"description":"商品评分(0-5)","nullable":true,"type":"number"},"product_status":{"description":"商品状态代码","nullable":true,"type":"number"},"region":{"description":"地区代码","nullable":true,"type":"string"},"seller_avatar":{"description":"店铺头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"nullable":true,"type":"array"},"seller_id":{"description":"店铺ID","nullable":true,"type":"string"},"shipping_fee":{"description":"运费","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"shop_name":{"description":"店铺名称","nullable":true,"type":"string"},"shop_total_sold_count":{"description":"店铺总销量","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"商品新品榜商品列表","items":{"properties":{"biz_type":{"description":"商家业务类型代码","nullable":true,"type":"number"},"ceiling_price":{"description":"最高价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","nullable":true,"type":"number"},"floor_price":{"description":"最低价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"id":{"description":"榜单实体唯一标识","type":"string"},"l1_category":{"description":"一级类目","nullable":true,"type":"string"},"l2_category":{"description":"二级类目","nullable":true,"type":"string"},"l3_category":{"description":"三级类目","nullable":true,"type":"string"},"product_gmv":{"description":"总GMV","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"product_gmv_for_last_3_days":{"description":"近 3 天销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"product_gmv_for_last_7_days":{"description":"近 7 天销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"product_id":{"description":"商品ID","nullable":true,"type":"string"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"nullable":true,"type":"array"},"product_name":{"description":"商品名称","nullable":true,"type":"string"},"product_rating":{"description":"商品评分(0-5)","nullable":true,"type":"number"},"product_sold_count":{"description":"总销量","nullable":true,"type":"number"},"product_sold_count_for_last_3_days":{"description":"近 3 天销量","nullable":true,"type":"number"},"product_sold_count_for_last_7_days":{"description":"近 7 天销量","nullable":true,"type":"number"},"product_status":{"description":"商品状态代码","nullable":true,"type":"number"},"region":{"description":"地区代码","nullable":true,"type":"string"},"seller_avatar":{"description":"店铺头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"nullable":true,"type":"array"},"seller_id":{"description":"店铺ID","nullable":true,"type":"string"},"shipping_fee":{"description":"运费","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"shop_name":{"description":"店铺名称","nullable":true,"type":"string"},"shop_total_sold_count":{"description":"店铺总销量","nullable":true,"type":"number"},"sold_count_trend":{"description":"销量趋势(近7天)","items":{"properties":{"timestamp":{"description":"Unix 毫秒级时间戳","type":"integer"},"value":{"description":"销量数值","type":"number"}},"type":"object"},"nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"商品销量榜商品列表","items":{"properties":{"biz_type":{"description":"商家业务类型代码","nullable":true,"type":"number"},"ceiling_price":{"description":"最高价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"commission_rate":{"description":"佣金率","nullable":true,"type":"number"},"country_code":{"description":"国家或地区代码","nullable":true,"type":"string"},"floor_price":{"description":"最低价","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"id":{"description":"榜单实体唯一标识","type":"string"},"interval_gmv":{"description":"统计周期销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_gmv_pop_growth_rate":{"description":"销售额环比增长率，原始比值","nullable":true,"type":"number"},"interval_product_sold_count_pop_growth_rate":{"description":"销量环比增长率，原始比值","nullable":true,"type":"number"},"interval_related_creator_count":{"description":"统计周期关联达人数","nullable":true,"type":"number"},"interval_sold_count":{"description":"统计周期销量","nullable":true,"type":"number"},"interval_total_gmv":{"description":"截至统计周期的累计销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_total_sold_count":{"description":"截至统计周期的累计销量","nullable":true,"type":"number"},"interval_video_play_count":{"description":"统计周期关联视频播放量","nullable":true,"type":"number"},"l1_category":{"description":"一级类目","nullable":true,"type":"string"},"l2_category":{"description":"二级类目","nullable":true,"type":"string"},"l3_category":{"description":"三级类目","nullable":true,"type":"string"},"product_id":{"description":"商品ID","nullable":true,"type":"string"},"product_images":{"description":"商品图片","items":{"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"nullable":true,"type":"array"},"product_name":{"description":"商品名称","nullable":true,"type":"string"},"product_rating":{"description":"商品评分(0-5)","nullable":true,"type":"number"},"product_status":{"description":"商品状态代码","nullable":true,"type":"number"},"region":{"description":"地区代码","nullable":true,"type":"string"},"seller_avatar":{"description":"店铺头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"nullable":true,"type":"array"},"seller_id":{"description":"店铺ID","nullable":true,"type":"string"},"shipping_fee":{"description":"运费","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"shop_name":{"description":"店铺名称","nullable":true,"type":"string"},"shop_total_sold_count":{"description":"店铺总销量","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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/trend":{"post":{"description":"按商品和日期范围查询 TikTok 商品的每日/累计销量、销售额、最高价和最低价、关联视频播放量、运费趋势及区间汇总指标。金额按市场货币返回，缺失点不等同于零；DE/FR/IT/ES 日增量优先使用 growth 字段。","operationId":"chuhaijiang-products-trend","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":{"example":{"entity_id_list":["1729508370969629931"],"time_filter":{"end_date_time":"20260919","granularity":0,"is_customized":true,"start_date_time":"20260913"}},"schema":{"additionalProperties":false,"description":"查询一个 TikTok 商品在指定日期范围内的每日趋势。设置商品 ID、开始日期和结束日期；granularity 填 0，is_customized 填 true。","properties":{"entity_id_list":{"description":"要查询的商品 ID，以字符串数组传入，一次仅支持一个商品，例如 [\"1729508370969629931\"]。商品 ID 可从「数据查询 / 商品数据」的商品搜索接口获取。","items":{"description":"TikTok 商品 ID","pattern":"^\\d+$","type":"string"},"maxItems":1,"minItems":1,"type":"array"},"time_filter":{"additionalProperties":false,"description":"查询日期范围，日期格式为 YYYYMMDD，按 UTC 日期统计，包含开始和结束日期。最早可用日期因商品、市场及指标而异，缺失数据不表示数值为 0。","properties":{"end_date_time":{"description":"结束日期（含），格式 YYYYMMDD，例如 20260919。建议按 SaaS 的最新可选日期查询：北京时间 15:00 前选前天，15:00 后选昨天；这是页面的数据更新约定，并非本接口强制校验或数据完整性保证。","example":"20260919","pattern":"^\\d{8}$","type":"string"},"granularity":{"description":"固定填 0，表示按天返回趋势。","enum":[0],"type":"integer"},"is_customized":{"description":"true：按指定时间范围统计；false：使用默认统计方式。","example":true,"type":"boolean"},"start_date_time":{"description":"开始日期（含），格式 YYYYMMDD，例如 20260913 表示 2026 年 9 月 13 日；应不晚于结束日期。当前接口未设置统一的最早日期或最大查询天数，实际可查范围取决于该商品各指标的数据覆盖，不能保证任意历史日期都有数据。","example":"20260913","pattern":"^\\d{8}$","type":"string"}},"required":["granularity","start_date_time","end_date_time","is_customized"],"type":"object"}},"required":["entity_id_list","time_filter"],"type":"object"}}},"description":"商品与时间区间","required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.6}},"schema":{"properties":{"data":{"properties":{"items":{"description":"商品趋势结果","items":{"description":"商品各项趋势和区间指标","properties":{"daily_gmv_trend":{"description":"每日销售额趋势，金额为对应市场货币；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"gmv_growth_in_given_time_range":{"description":"DE/FR/IT/ES 市场日增销售额汇总","type":"number"},"gmv_growth_trend":{"description":"真实日增销售额趋势，DE/FR/IT/ES 市场展示日增量时优先使用；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"gmv_in_given_time_range":{"description":"区间销售额，金额为对应市场货币","type":"number"},"id":{"description":"商品 ID","type":"string"},"related_creators_in_given_time_range":{"description":"区间关联达人数","type":"number"},"related_lives_in_given_time_range":{"description":"区间关联直播数","type":"number"},"related_videos_in_given_time_range":{"description":"区间关联视频数","type":"number"},"sold_count_growth_in_given_time_range":{"description":"DE/FR/IT/ES 市场日增销量汇总","type":"number"},"sold_count_growth_trend":{"description":"真实日增销量趋势，DE/FR/IT/ES 市场展示日增量时优先使用；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"sold_count_in_given_time_range":{"description":"区间销量","type":"number"},"sold_count_trend":{"description":"每日销量趋势；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"total_ceiling_price_trend":{"description":"每日最高价趋势，金额为对应市场货币；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"total_floor_price_trend":{"description":"每日最低价趋势，金额为对应市场货币；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"total_gmv_trend":{"description":"累计销售额趋势，金额为对应市场货币；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"total_shipping_fee_trend":{"description":"每日运费趋势，金额为对应市场货币；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"total_sold_count_trend":{"description":"累计销量趋势；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"video_convert_ratio_in_given_time_range":{"description":"区间销量除以视频播放量的转化率，原始比值（非百分数）","type":"number"},"video_gpm_in_given_time_range":{"description":"区间视频千次播放销售额","type":"number"},"video_play_count_delta":{"description":"每日关联视频播放量趋势；字段或数据点可能缺失","items":{"description":"每日数据点","properties":{"date":{"description":"UTC Unix 秒时间戳","type":"integer"},"is_predicted":{"description":"为 true 时表示该点为预估值；可能不返回此字段","type":"boolean"},"value":{"description":"指标数值；null 表示无数据，不能当作 0","nullable":true,"type":"number"}},"required":["date","value"],"type":"object"},"nullable":true,"type":"array"},"video_play_count_in_given_time_range":{"description":"区间关联视频播放量","type":"number"}},"type":"object"},"type":"array"},"total_count":{"description":"返回商品数量，由 items 长度计算","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":"RESOURCE_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}":{"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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"店铺热推榜结果列表","items":{"properties":{"biz_type":{"description":"商家业务类型代码","nullable":true,"type":"number"},"id":{"description":"榜单实体唯一标识","type":"string"},"interval_related_creator_count":{"description":"统计周期关联达人数","nullable":true,"type":"number"},"interval_total_related_creator_count":{"description":"累计关联达人数","nullable":true,"type":"number"},"interval_total_related_shop_creator_count":{"description":"累计关联店铺达人数","nullable":true,"type":"number"},"interval_total_related_video_creator_count":{"description":"累计关联视频达人数","nullable":true,"type":"number"},"interval_total_related_videos_count":{"description":"累计关联视频数","nullable":true,"type":"number"},"region":{"description":"地区代码","nullable":true,"type":"string"},"seller_avatar":{"description":"店铺头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"nullable":true,"type":"array"},"seller_id":{"description":"店铺ID","nullable":true,"type":"string"},"seller_main_category":{"description":"店铺主营品类 ID","nullable":true,"type":"string"},"shop_name":{"description":"店铺名称","nullable":true,"type":"string"},"shop_product_count":{"description":"商品数量","nullable":true,"type":"number"},"shop_rating":{"description":"店铺评分","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"schema":{"properties":{"data":{"properties":{"items":{"description":"店铺销量榜结果列表","items":{"properties":{"biz_type":{"description":"商家业务类型代码","nullable":true,"type":"number"},"id":{"description":"榜单实体唯一标识","type":"string"},"interval_gmv":{"description":"统计周期销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_gmv_pop_growth_rate":{"description":"销售额环比增长率，原始比值","nullable":true,"type":"number"},"interval_related_creator_count":{"description":"统计周期关联达人数","nullable":true,"type":"number"},"interval_sold_count":{"description":"统计周期销量","nullable":true,"type":"number"},"interval_sold_count_growth_rate":{"description":"销量环比增长率，原始比值","nullable":true,"type":"number"},"interval_total_gmv":{"description":"截至统计周期的累计销售额","nullable":true,"properties":{"unit":{"description":"市场或货币单位标识","type":"string"},"value":{"description":"金额数值","type":"number"}},"type":"object"},"interval_total_related_creator_count":{"description":"累计关联达人数","nullable":true,"type":"number"},"interval_total_sold_count":{"description":"截至统计周期的累计销量","nullable":true,"type":"number"},"region":{"description":"地区代码","nullable":true,"type":"string"},"seller_avatar":{"description":"店铺头像","nullable":true,"properties":{"thumb_url":{"description":"缩略图地址","type":"string"},"url":{"description":"原图地址","type":"string"}},"type":"object"},"seller_business_info":{"description":"商家主体信息","items":{"type":"string"},"nullable":true,"type":"array"},"seller_id":{"description":"店铺ID","nullable":true,"type":"string"},"seller_main_category":{"description":"店铺主营品类 ID","nullable":true,"type":"string"},"shop_name":{"description":"店铺名称","nullable":true,"type":"string"},"shop_product_count":{"description":"商品数量","nullable":true,"type":"number"},"shop_rating":{"description":"店铺评分","nullable":true,"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":"在 TikTok 或 Facebook 上点赞或取消点赞评论。action 固定传 LIKE（点赞）或 UNLIKE（取消点赞）；YouTube、Instagram 不支持此操作。","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 = 取消点赞","enum":["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":999.9,"credits_cost":0.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":"RESOURCE_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 = 仅返回账号所有者已回复的评论；false 或不传 = 不按此条件筛选","type":"boolean"},"include_replies":{"default":false,"description":"是否在每条一级评论下内联返回回复；默认 false","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,"minimum":1,"type":"integer"},"max_replies":{"default":3,"description":"每条一级评论最多内联返回的回复数，仅 include_replies=true 时生效；默认 3","minimum":1,"type":"integer"},"owner_replied":{"description":"是否已回复筛选。true = 已回复，false = 未回复，不传 = 全部","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":"平台筛选（多选）","items":{"enum":["tiktok","instagram","youtube","facebook"],"type":"string"},"type":"array"},"published_after":{"description":"评论发布时间起始（Unix 时间戳，秒）","type":"integer"},"published_before":{"description":"评论发布时间截止（Unix 时间戳，秒）","type":"integer"},"sort_by":{"description":"排序字段。published_at = 发布时间（默认），like_count = 点赞数","enum":["published_at","like_count"],"type":"string"},"sort_order":{"description":"排序方向。desc = 降序（默认），asc = 升序","enum":["desc","asc"],"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"comments":{"description":"一级评论列表","items":{"properties":{"author":{"description":"评论作者信息","properties":{"avatar_url":{"description":"作者头像 URL","type":"string"},"display_name":{"description":"作者显示名称","type":"string"},"is_verified":{"description":"作者是否为平台认证账号","type":"boolean"},"platform_user_id":{"description":"作者在平台侧的用户 ID","type":"string"},"profile_url":{"description":"作者主页 URL","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"},"parent_comment_id":{"description":"父评论的平台侧 ID；一级评论不返回","type":"string"},"platform":{"description":"来源平台","enum":["tiktok","instagram","youtube","facebook"],"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"},"replies":{"description":"内联回复；仅 include_replies=true 时可能返回","items":{"properties":{"author":{"description":"评论作者信息","properties":{"avatar_url":{"description":"作者头像 URL","type":"string"},"display_name":{"description":"作者显示名称","type":"string"},"is_verified":{"description":"作者是否为平台认证账号","type":"boolean"},"platform_user_id":{"description":"作者在平台侧的用户 ID","type":"string"},"profile_url":{"description":"作者主页 URL","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"},"parent_comment_id":{"description":"父评论的平台侧 ID；一级评论不返回","type":"string"},"platform":{"description":"来源平台","enum":["tiktok","instagram","youtube","facebook"],"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"},"synced_at":{"description":"最近一次同步时间（Unix 时间戳，秒）","type":"integer"},"text":{"description":"评论或回复内容","type":"string"},"visibility":{"description":"评论可见性；不同平台支持程度可能不同","enum":["PUBLIC","HIDDEN","FRIENDS_ONLY","UNKNOWN"],"type":"string"}},"type":"object"},"type":"array"},"reply_count":{"description":"回复数","type":"integer"},"synced_at":{"description":"最近一次同步时间（Unix 时间戳，秒）","type":"integer"},"text":{"description":"评论或回复内容","type":"string"},"visibility":{"description":"评论可见性；不同平台支持程度可能不同","enum":["PUBLIC","HIDDEN","FRIENDS_ONLY","UNKNOWN"],"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":"RESOURCE_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，最大 100","maximum":100,"minimum":1,"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":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"limit":{"description":"每页条数","type":"integer"},"page":{"description":"当前页码","type":"integer"},"replies":{"description":"指定评论线程下的回复列表","items":{"properties":{"author":{"description":"评论作者信息","properties":{"avatar_url":{"description":"作者头像 URL","type":"string"},"display_name":{"description":"作者显示名称","type":"string"},"is_verified":{"description":"作者是否为平台认证账号","type":"boolean"},"platform_user_id":{"description":"作者在平台侧的用户 ID","type":"string"},"profile_url":{"description":"作者主页 URL","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"},"parent_comment_id":{"description":"父评论的平台侧 ID；一级评论不返回","type":"string"},"platform":{"description":"来源平台","enum":["tiktok","instagram","youtube","facebook"],"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"},"synced_at":{"description":"最近一次同步时间（Unix 时间戳，秒）","type":"integer"},"text":{"description":"评论或回复内容","type":"string"},"visibility":{"description":"评论可见性；不同平台支持程度可能不同","enum":["PUBLIC","HIDDEN","FRIENDS_ONLY","UNKNOWN"],"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":"从平台拉取评论并同步到本地。本接口同步执行，在本次处理完成后返回统计结果。传 platform_video_id 时仅同步指定视频；不传时同步账号下当前符合同步条件的视频，系统可能根据视频活跃度、最近同步时间、防抖和平台退避策略跳过部分视频。同步后可通过「评论列表」接口查看结果。","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":"可选。传入时仅同步指定视频；不传时同步该账号下符合当前同步条件的视频，部分视频可能因活跃度分档、防抖或平台退避策略被跳过","type":"string"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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/facebook/auth-url":{"get":{"description":"为当前 API Key 所属用户生成 Facebook 网页授权链接，适合云手机、代运营或账号持有人不在身边的场景。\n\n将返回的 `auth_url` 发送给 Facebook 账号持有人。对方在任意浏览器登录并确认授权后，系统会绑定其具有内容发布权限的所有 Facebook Page。使用同一响应中的 `ref` 调用「查询社媒授权绑定状态」接口（历史兼容路径 `POST /open/v1/social/tiktok/bind-status`），轮询至 `status=bound`。\n\n注意：绑定状态响应中的单个 `account` 仅代表首个成功绑定的 Page；如需获取本次授权绑定的全部 Page，请调用「社媒账号列表」。链接长期有效且可重复使用，请仅发送给可信的账号持有人。","operationId":"social-facebook-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.facebook.com/v24.0/dialog/oauth?client_id=1234567890\u0026redirect_uri=https%3A%2F%2Fwww.chuhaijiang.com%2Fapi%2Fauth%2Ffacebook%2Fcallback\u0026scope=...\u0026response_type=code\u0026state=ttweb%3A...","ref":"bind_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUu0","state":"ttweb:9f8e...:eyJ1aWQ...af46"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_url":{"description":"Facebook 授权页完整链接。发送给账号持有人在任意浏览器打开并完成授权","type":"string"},"ref":{"description":"本次授权的绑定关联标识，以 bind_ 开头；请原样传给历史兼容路径 POST /open/v1/social/tiktok/bind-status 查询绑定回执","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":"RESOURCE_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":"获取Facebook授权链接","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"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":999.9,"credits_cost":0.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":"RESOURCE_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":{"total":3},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":{"total":87},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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":{"total":87},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":{"total":156},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":{"id":987655,"platform_message_id":"wamid.HBgLOD...","status":"sent","str_id":"987655"},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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":{"cdn_url":"https://oss.chuhaijiang.com/im/2026/07/10/20260710153000_photo.jpg","object_key":"im/2026/07/10/20260710153000_photo.jpg","presigned_url":"https://datanebula-object.s3.us-west-2.amazonaws.com/im/2026/07/10/20260710153000_photo.jpg?X-Amz-...","s3_bucket":"datanebula-object"},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.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":"RESOURCE_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/instagram/auth-url":{"get":{"description":"为当前 API Key 所属用户生成 Instagram 网页授权链接，适合云手机、代运营或账号持有人不在身边的场景。仅支持 Instagram Business 或 Creator 专业账号。\n\n将返回的 `auth_url` 发送给 Instagram 账号持有人。对方在任意浏览器登录并确认授权后，使用同一响应中的 `ref` 调用「查询社媒授权绑定状态」接口（历史兼容路径 `POST /open/v1/social/tiktok/bind-status`），轮询至 `status=bound`。\n\n注意：链接长期有效且可重复使用，任何人打开并完成授权都会将其 Instagram 账号绑定到您的团队，请仅发送给可信的账号持有人。","operationId":"social-instagram-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.instagram.com/oauth/authorize?client_id=1234567890\u0026redirect_uri=https%3A%2F%2Fwww.chuhaijiang.com%2Fapi%2Fauth%2Finstagram%2Fcallback\u0026scope=...\u0026response_type=code\u0026state=ttweb%3A...","ref":"bind_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUu0","state":"ttweb:9f8e...:eyJ1aWQ...af46"},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_url":{"description":"Instagram 授权页完整链接。发送给账号持有人在任意浏览器打开并完成授权","type":"string"},"ref":{"description":"本次授权的绑定关联标识，以 bind_ 开头；请原样传给历史兼容路径 POST /open/v1/social/tiktok/bind-status 查询绑定回执","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":"RESOURCE_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":"获取Instagram授权链接","tags":["社媒管理/1.账号管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/location/search":{"post":{"description":"按指定 TikTok Business 账号搜索发布位置标签，返回可用于发布配置 location_id 和 location_name 的匹配地点。结果由 TikTok 实时返回，最多 20 条。","operationId":"chuhaijiang-social-location-search","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":"当前用户拥有的 TikTok Business 平台账号 ID。来自「社媒账号列表」（社媒管理 \u003e 账号管理）返回的 id 字段","minimum":1,"type":"integer"},"search_query":{"description":"地点搜索关键词，长度 1-100 个字符，例如 New York。结果与指定账号及 TikTok 可用范围相关","maxLength":100,"minLength":1,"type":"string"}},"required":["platform_account_id","search_query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"locations":{"description":"匹配的 TikTok 发布位置标签，最多 20 条","items":{"properties":{"location_address":{"description":"位置地址信息，仅用于展示和区分同名地点","type":"string"},"location_id":{"description":"位置标签 ID。发布时作为 platform_config.location_id，并与 location_name 成对传入","type":"string"},"location_name":{"description":"位置名称。发布时必须与对应的 location_id 成对传入","type":"string"}},"type":"object"},"maxItems":20,"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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"TikTok 地点搜索请求无效。","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"请求参数、账号归属或账号平台不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok 地点服务返回错误。","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok 地点服务或内部依赖未能完成请求。"},"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":["社媒管理/2.视频发布"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.read"}},"/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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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"},"is_ad":{"description":"该帖子当前是否正被用于广告投放。仅确认值为 true 时返回；字段缺失不表示已确认不是广告，也不等同于发布参数 is_ads_only。","type":"boolean"},"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":"RESOURCE_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":"主动触发单条发布记录的平台指标刷新（播放/点赞/评论/分享等），获取当前最新累计值，适用于拉取详情前确保数据新鲜度。本 OpenAPI 仅提供同步刷新：请将 background 设为 false，或省略该字段；请求会等待平台数据刷新完成后返回最终结果。同步刷新通常需要数秒，少数情况可能需要数十秒，建议客户端设置 60 秒以上的请求超时时间。注意：本接口刷新的是当前累计指标，不修正历史日级数据。\n\n频率限制：同一视频刷新成功后有 60 秒冷却窗口，窗口内重复调用返回 cooling，表示数据已是最新，不会重复请求平台；已删除的视频返回 deleted。","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":"同步刷新标志。请传 false 或省略；公开接口会等待平台指标刷新完成后返回最终结果，不支持 background=true 的异步调用方式","enum":[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":{"status":"cooling"},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.2}},"schema":{"properties":{"data":{"description":"返回同步刷新的最终处理结果；刷新后的指标通过「发布记录详情」接口查询。","properties":{"status":{"description":"同步刷新结果。refreshed=刷新完成；cooling=60 秒冷却窗口内，数据已是最新；not_found=平台未找到该视频；skipped=演示账号等场景跳过；deleted=视频已删除；failed=刷新失败。调用方必须检查 status，不能只判断 HTTP 状态。","enum":["cooling","refreshed","not_found","skipped","deleted","failed"],"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":"各发布目标的详细状态。单个目标结果以 status 为准；失败时读取 error_message","items":{"properties":{"created_at":{"description":"发布任务创建时间，Unix 时间戳（秒）","type":"integer"},"description":{"description":"发布描述","type":"string"},"error_message":{"description":"面向用户映射后的失败原因；status=failed 时用于判断下一步处理","type":"string"},"id":{"description":"发布任务 ID","type":"integer"},"platform_account_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"},"published_at":{"description":"实际发布时间，Unix 时间戳（秒）；尚未发布时为 null","nullable":true,"type":"integer"},"region":{"description":"TikTok Shop 账号区域，例如 US、BR、MX；非 TikTok Shop 账号通常为空","nullable":true,"type":"string"},"retry_count":{"description":"已执行的重试次数","type":"integer"},"scheduled_at":{"description":"计划发布时间，Unix 时间戳（秒）；未定时发布时为 null","nullable":true,"type":"integer"},"stage":{"description":"当前阶段描述","type":"string"},"status":{"description":"发布状态：pending / uploading / processing / published / failed / cancelled","enum":["pending","scheduled","uploading","processing","published","failed","cancelled"],"type":"string"},"tags":{"description":"发布记录标签","items":{"type":"string"},"type":"array"},"title":{"description":"发布标题","type":"string"},"updated_at":{"description":"发布任务最近更新时间，Unix 时间戳（秒）","type":"integer"},"video_id":{"description":"关联的内容记录 ID","type":"integer"}},"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=全部成功；completed_with_errors=一个或多个目标失败（包括全部失败）；cancelled=已取消；failed=历史兼容状态，不是当前常规终态","enum":["in_progress","completed","completed_with_errors","cancelled","failed"],"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":"同步受理视频、图文或纯文本内容，并异步发布到多个社媒平台。TikTok Shop 挂车视频必须在 publications[].platform_config 中同时提供 product_id 和 product_title；TikTok Shop 挂车图文必须提供 post_type，并按发布类型提供 links 或 shop_info，music_id 只是可选音乐配置，不能单独构成挂车配置。返回 session_token 后请调用「发布会话状态」查询各目标最终结果。","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":"content_type=video 时与 bucket_name 同时必填。普通上传填写「生成上传预签名URL」返回的 object_key；加速上传填写 os_key；仅用于视频，请勿与 media_items 同时传入","type":"string"},"bucket_name":{"description":"content_type=video 时与 bucket_key 同时必填。普通上传填写「生成上传预签名URL」返回的 s3_bucket；加速上传填写 os_bucket；仅用于视频，请勿与 media_items 同时传入","type":"string"},"content_type":{"default":"video","description":"内容类型：video=视频（默认），image=图片或图片轮播，text=纯文本（仅 Twitter）。媒体字段按内容类型条件互斥：video 使用顶层 bucket_name 和 bucket_key，image 使用 media_items，text 不传上述媒体字段；请勿同时传入顶层 bucket 字段和 media_items","enum":["video","image","text"],"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":"可选的视频时长，单位秒；Instagram Reels 使用帧封面（reel_cover.mode=frame）时必须传有效正数","type":"number"},"file_size":{"description":"可选的媒体文件大小，单位字节；作为发布记录的媒体元数据","type":"integer"},"media_items":{"description":"content_type=image 时必填的图片列表。普通上传使用 s3_bucket/object_key，加速上传使用 os_bucket/os_key。数量上限：TikTok Business/TikTok Shop 35 张，Instagram/Facebook 10 张，Twitter 4 张；仅用于图片，请勿与顶层 bucket_name、bucket_key 同时传入","items":{"properties":{"bucket_key":{"description":"图片路径：普通上传填写 object_key，加速上传填写 os_key","type":"string"},"bucket_name":{"description":"图片存储桶：普通上传填写 s3_bucket，加速上传填写 os_bucket","type":"string"},"order":{"description":"排序序号（从 1 开始）","type":"integer"}},"required":["bucket_name","bucket_key","order"],"type":"object"},"minItems":1,"type":"array"},"publications":{"description":"发布目标列表。视频支持 TikTok Business、TikTok Personal、TikTok Shop、YouTube、Instagram、Facebook、Twitter；图片支持 TikTok Business、TikTok Shop、Instagram、Facebook、Twitter；纯文本仅支持 Twitter。接口同步返回仅表示任务已受理，平台发布在后台执行","items":{"properties":{"description":{"description":"发布到目标平台的内容描述","type":"string"},"platform_account_id":{"description":"目标社媒账号 ID（从「社媒账号列表」接口获取）","type":"integer"},"platform_config":{"description":"【TikTok Shop 挂车必读】\n- 挂车视频（content_type=video）：platform_config 必须同时包含 product_id 和 product_title。\n- 挂车图文（content_type=image）：platform_config 必须包含 post_type；只传 music_id 会被判定为“发布配置不完整（缺少发布类型）”。\n- 商品锚点 post_type=1/3 必须传 links；店铺锚点 post_type=2 必须传 shop_info。\n- music_id 仅用于选择音乐，不代表已选择挂车商品或挂车类型。\n\n平台特定发布配置（JSON 字符串）。字段仅在对应平台和内容类型下生效；目标平台由 platform_account_id 对应的账号决定，普通 TikTok 账号传入 TikTok Shop 商品字段不会切换为挂车发布。\n\nTikTok Business：\n- privacy (string): PUBLIC_TO_EVERYONE / MUTUAL_FOLLOW_FRIENDS / FOLLOWER_OF_CREATOR / SELF_ONLY。Business API 商家授权场景通常遵循账号默认隐私设置\n- disable_comment (boolean): 禁用评论\n- disable_duet (boolean): 禁用合拍，仅视频\n- disable_stitch (boolean): 禁用拼接，仅视频\n- is_aigc (boolean): AI 生成内容声明\n- thumbnail_offset (integer): 视频封面取帧时间，毫秒\n- photo_cover_index (integer): 图文封面图片索引\n- is_ads_only (boolean): 仅广告展示；启用后内容不展示在账号主页且不可恢复，仅视频\n- music_sound_id (string): 商用音乐 song_clip_id，支持视频和图文\n- music_sound_volume (integer): 音乐音量 0-100，默认 100，仅视频\n- music_sound_start / music_sound_end (integer): 音乐片段起止时间，毫秒，仅视频；结束时间必须大于开始时间\n- video_original_sound_volume (integer): 原视频音量 0-100\n- auto_add_music (boolean): TikTok 自动配乐，仅图文；与 music_sound_id 二选一\n- location_id / location_name (string): 位置标签 ID 和名称，必须成对传入且相互对应\n\nTikTok Shop 挂车视频（目标账号为 TikTok Shop 且 content_type=video）：\n- product_id / product_title (string): 必须同时传入；product_title 最多 30 个字符且不能包含标点或 emoji\n- enable_precheck (boolean): 发布前执行商品视频预检\n- music_id (string): TikTok Shop 音乐 ID\n- cover_mode (string): custom-upload / video-frame；自定义封面使用顶层 cover_bucket_name 和 cover_bucket_key\n- cover_timestamp_ms (integer): video-frame 的取帧时间，毫秒，0 表示首帧\n- is_ai_generated (boolean): AI 生成内容声明\n\nTikTok Shop 挂车图文（目标账号为 TikTok Shop 且 content_type=image）：\n- post_type (string，TikTok Shop 图文必填): 1=多图一个商品锚点；2=店铺锚点；3=一图一个商品锚点。只传 music_id 不构成有效挂车配置\n- links (array): post_type=1 时必填 1-15 项；post_type=3 时必填且数量、顺序必须与图片一致。每项 product_id 必填；link_title 不要直接复制商品全名，应使用精简挂车标题：去除首尾空白后最多 30 个 Unicode 字符，建议仅使用字母、数字和普通空格，不允许 -、'、\u0026、/、.、逗号等标点、其他符号或 emoji\n- shop_info (object): post_type=2 时必填；group_type=1/2/3，类型 2/3 必须传 group_id\n- music_id (string): 可选音乐 ID\n- 图片最多 35 张；单张最大 10MB，宽高比须在 9:16 至 16:9 之间\n\nYouTube：\n- privacy (string): public / private / unlisted\n- tags (array): YouTube 视频标签\n- categoryId (string)、embeddable (boolean)、license (string)、self_declared_made_for_kids (boolean)\n- cover_mode (string): custom-upload；缩略图使用顶层 cover_bucket_name 和 cover_bucket_key，仅 JPEG/PNG、最大 2MB\n\nInstagram Reels：\n- media_type (string): REELS\n- share_to_feed (boolean): 是否同时分享到主页动态\n- reel_cover (object): mode=custom 时使用顶层封面 bucket 字段；mode=frame 时必须传 thumb_offset_ms，且顶层 duration 必须为有效正数\n\n示例（TikTok Business）：{\"is_aigc\":true,\"location_id\":\"123\",\"location_name\":\"New York\",\"thumbnail_offset\":1000}\n示例（TikTok Shop 挂车视频）：{\"product_id\":\"123456789\",\"product_title\":\"商品名称\",\"is_ai_generated\":true,\"cover_mode\":\"video-frame\",\"cover_timestamp_ms\":1000}\n示例（TikTok Shop 挂车图文）：{\"post_type\":\"1\",\"links\":[{\"product_id\":\"123456789\",\"link_title\":\"Botanical Cream Tee\"}],\"music_id\":\"optional-music-id\"}\nlink_title 合法示例：Botanical Cream Tee\nlink_title 非法示例：Bohemian Moth Moon Botanical Fleetwood Mac Cream Casual Tee（超过 30 字符）、Moth-Moon Tee、Women's Tee（含标点）","type":"string"},"scheduled_at":{"description":"定时发布时间，Unix 时间戳（秒）。过去时间或距当前不足 5 分钟按立即发布处理；定时发布最远支持未来 90 天","type":"integer"},"tags":{"description":"发布记录标签，仅保存到我方记录，不会自动拼接为 TikTok/Instagram hashtag；YouTube 视频标签请使用 platform_config.tags","items":{"type":"string"},"type":"array"},"title":{"description":"发布到目标平台的内容标题。TikTok Business 图文最多 90 个 UTF-16 字符单位（部分 emoji 计 2 个）；Facebook 视频标题最多 255 个 UTF-8 字节","type":"string"}},"required":["platform_account_id","title"],"type":"object"},"minItems":1,"type":"array"},"video_description":{"description":"内容发布记录描述，可选；用于我方保存发布记录，不替代 publications[].description","type":"string"},"video_title":{"description":"内容发布记录标题，所有内容类型均必填；用于我方保存和管理发布记录，不替代 publications[].title","type":"string"}},"required":["video_title","publications"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":1}},"schema":{"properties":{"data":{"properties":{"session_token":{"description":"发布会话 Token。仅表示任务已受理，不代表各平台发布成功；请调用「发布会话状态」轮询最终结果","type":"string"},"skipped_accounts":{"description":"因频率限制而未受理的账号信息。非空表示发生部分受理，调用方必须检查；null、缺省或空数组表示没有账号被跳过","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":"RESOURCE_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/publish/upload-and-publish-by-url":{"post":{"description":"部分客户专用的 URL 直发通道。素材不经过出海匠对象存储，而是由 TikTok 或 Facebook 在实际发布时从调用方提供的 HTTPS URL 回源拉取。\n\n支持 TikTok Business 账号和 Facebook 主页账号的视频、图文发布；同一次请求可以混合填写两类账号。不支持 TikTok Personal、TikTok Shop、Instagram、YouTube、Twitter。\n\n请求成功仅表示发布会话已创建，不代表所有账号已经发布成功。请使用「社媒管理 / 2.视频发布」分类下的「发布会话状态」接口 POST /open/v1/social/publish/session，传入 session_token 查询最终结果。\n\n素材与 URL 要求：\n- video_url、cover_url、media_items[].url 必须使用 HTTPS，且域名必须在我方 URL 直发白名单内。\n- TikTok 使用的域名还必须完成 TikTok URL 归属验证；Facebook 使用同一份入口白名单。\n- 出海匠不会下载、转存、探测、转码或压缩素材。调用方必须保证格式、尺寸、大小和链接有效期符合目标平台要求。\n- 立即发布时，链接需保持到平台完成拉取；定时发布时，签名链接必须在 scheduled_at 时仍然有效。\n- 图文入口最多接收 35 张；只要 publications 中包含 Facebook 账号，请控制在 10 张以内，否则 Facebook 会在发布阶段失败。\n- 图文 order 必须是 0..n-1 的唯一连续排列。\n- 该通道没有我方素材副本，不支持后台重新发布；失败后需重新调用本接口。\n\nFacebook 特有规则：\n- Facebook 视频 title 最长 255 个 UTF-8 字节；中文通常约 85 个字，emoji 通常占 4 字节。视频前台主要展示 description，title 仅作为元数据。\n- Facebook 视频 description 的回退顺序为：publications[].description → platform_config 中的 description → video_description → 有效标题。\n- Facebook 图文文案由 publications[].title 与 publications[].description 组成；两者都有值时，中间加入两个换行。\n- Facebook 不支持自定义 cover_url。传入后发布阶段会忽略，但入口仍会校验该 URL；仅发布 Facebook 时请省略。\n- 素材域名必须允许 User-Agent facebookexternalhit/1.1 访问。robots.txt 或防盗链返回 403 可能导致 Meta 暂时按域名拒绝后续素材。\n- 建议视频使用 MP4（H.264/AAC），图片使用 JPG/PNG。\n\nFacebook 图文请求示例：\n{\n  \"content_type\": \"image\",\n  \"video_title\": \"素材标题\",\n  \"media_items\": [\n    {\"url\": \"https://your-allowlisted-domain.example/a.jpg\", \"order\": 0},\n    {\"url\": \"https://your-allowlisted-domain.example/b.jpg\", \"order\": 1}\n  ],\n  \"publications\": [\n    {\"platform_account_id\": 12345, \"title\": \"标题\", \"description\": \"描述\"}\n  ],\n  \"source_type\": \"openapi\",\n  \"source_id\": \"your-business-id\"\n}\n\nFacebook 常见失败：\n- code 389 / Unable to fetch video file from URL：Facebook 无法拉取文件，请检查公网访问、链接有效期和 facebookexternalhit 放行。\n- subcode 1363143：视频标题超过 255 个 UTF-8 字节。\n- code 6000：视频格式不支持，建议改为 MP4（H.264/AAC）。\n- code 6001：视频文件过大，请压缩后重试。\n- code 190：主页授权已过期或无效，请在账号管理中重新连接。\n- code 368：主页需要管理员先在 Facebook 手机 App 完成身份验证。\n- publish-by-url only supports tiktok and facebook accounts：传入了不支持的平台账号。\n- bucket_name and bucket_key are required：素材 URL 不是 HTTPS，或域名不在入口白名单内。","operationId":"chuhaijiang-social-publish-by-url","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"default":"video","description":"内容类型：video=视频，image=图文；默认 video。","enum":["video","image"],"type":"string"},"cover_url":{"description":"TikTok 可选自定义封面 HTTPS 直链，须满足与 video_url 相同的入口白名单限制。Facebook 不支持并会在发布阶段忽略；但只要传入，入口仍会校验 HTTPS 和白名单，因此仅发布 Facebook 时请省略。","format":"uri","type":"string"},"media_items":{"description":"图文素材列表；content_type=image 时必填，入口最多 35 张。只要包含 Facebook 账号，请控制在 10 张以内，否则 Facebook 会在发布阶段失败。order 必须组成 0..n-1 的唯一连续排列。","items":{"properties":{"order":{"description":"图片顺序，从 0 开始；同一请求内不可重复，所有值必须组成 0..n-1。","minimum":0,"type":"integer"},"url":{"description":"图片 HTTPS 直链，域名必须在 URL 直发白名单内；发布到 Facebook 时须允许 facebookexternalhit/1.1 拉取。","format":"uri","type":"string"}},"required":["url","order"],"type":"object"},"maxItems":35,"minItems":1,"type":"array"},"publications":{"description":"发布目标列表，支持 TikTok Business 和 Facebook 主页账号，也可混合发布。每个账号可独立设置文案、平台配置和定时发布时间。","items":{"properties":{"description":{"description":"发布描述。TikTok 用作内容描述；Facebook 视频前台实际展示该字段，未传时依次回退到 platform_config.description、video_description、有效标题；Facebook 图文会将 title 与 description 用两个换行拼接为文案。","type":"string"},"platform_account_id":{"description":"目标平台账号 ID。仅支持 TikTok Business 账号或 Facebook 主页账号；同一请求可混合两类账号。","type":"integer"},"platform_config":{"description":"平台专用配置 JSON 字符串。Facebook 无需配置；Facebook 视频仅在 publications[].description 为空时读取其中的 description 作为兼容回退，建议直接填写 publications[].description。Facebook 图文忽略该字段。\n\nTikTok Business 可用字段：\n- privacy (string)：隐私设置，通常遵循账号默认设置\n- disable_comment (boolean)：禁用评论\n- disable_duet (boolean)：禁用合拍，仅视频\n- disable_stitch (boolean)：禁用拼接，仅视频\n- is_aigc (boolean)：AI 生成内容声明\n- thumbnail_offset (integer)：视频封面取帧时间，毫秒；传 cover_url 时忽略\n- music_sound_id (string)：商用音乐 song_clip_id\n- music_sound_volume (integer)：音乐音量，0-100\n- music_sound_start (integer)：音乐开始时间，毫秒且不小于 0\n- music_sound_end (integer)：音乐结束时间，毫秒且大于开始时间\n- video_original_sound_volume (integer)：原视频音量，0-100\n- auto_add_music (boolean)：TikTok 自动配乐，仅图文；与 music_sound_id 二选一\n- location_id (string)：位置标签 ID，必须与 location_name 成对传入\n- location_name (string)：位置名称，必须与 location_id 成对传入且相互对应\n\n示例：{\"is_aigc\":true,\"location_id\":\"123\",\"location_name\":\"New York\"}","type":"string"},"scheduled_at":{"description":"定时发布时间，Unix 秒。不传、0、过去时间或距当前不足 5 分钟时立即发布；有效定时范围为距当前 5 分钟至 90 天。定时发布时素材 URL 必须在执行时仍然有效。","type":"integer"},"tags":{"description":"TikTok 标签列表。Facebook 不会自动追加该字段；Facebook 话题标签请直接写入 description。","items":{"description":"TikTok 标签，例如 #fyp","type":"string"},"type":"array"},"title":{"description":"必填。TikTok 的发布标题；Facebook 视频的元数据标题，最长 255 个 UTF-8 字节且不在 Reels 前台展示；Facebook 图文文案的标题部分。","type":"string"}},"required":["platform_account_id","title"],"type":"object"},"minItems":1,"type":"array"},"source_id":{"description":"可选的调用方业务标识，原样保存，用于关联调用方自己的素材或任务。","type":"string"},"source_type":{"description":"可选的素材业务来源，原样保存；OpenAPI 调用建议填写 openapi。","type":"string"},"video_description":{"description":"素材记录描述，可选。Facebook 视频在 publications[].description 和 platform_config.description 均为空时，会使用该字段作为前台文案。","type":"string"},"video_title":{"description":"素材记录标题，必填，用于出海匠保存和管理发布记录；Facebook 视频 publications[].title 为空字符串时还会作为有效标题。","type":"string"},"video_url":{"description":"视频 HTTPS 直链；content_type=video 时必填。域名必须在 URL 直发白名单内；发布到 TikTok 时还须完成 TikTok URL 归属验证，发布到 Facebook 时须允许 facebookexternalhit/1.1 拉取。","format":"uri","type":"string"}},"required":["video_title","publications"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":1}},"schema":{"properties":{"data":{"description":"请求成功仅表示发布会话已创建，不代表所有账号已发布成功；请继续查询发布会话状态。","properties":{"session_token":{"description":"发布会话 Token。请调用「社媒管理 / 2.视频发布」分类下的「发布会话状态」接口 POST /open/v1/social/publish/session，传入该值轮询最终进度。","type":"string"},"skipped_accounts":{"description":"因频率限制被跳过的账号信息列表；正常情况下为空数组。","items":{"description":"被跳过的账号信息","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":"RESOURCE_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 发布 TikTok 与 Facebook 内容","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":999.9,"credits_cost":0.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 归因分解、高曝光低转化滞销品","nullable":true,"properties":{"available_date":{"description":"可用分析数据日期","type":"string"},"conversion":{"description":"转化率字符串","type":"string"},"gmv_attribution":{"description":"销售额变化归因，方向性估算","properties":{"delta_gmv":{"description":"销售额环比变化字符串","type":"string"},"drivers":{"description":"变化驱动因素","items":{"properties":{"contribution":{"description":"对销售额变化的贡献额字符串，可带正负号","type":"string"},"driver":{"description":"驱动因素：visitors、conversion、aov 或 oos","type":"string"},"note":{"description":"指标说明","type":"string"}},"type":"object"},"type":"array"},"lead_driver":{"description":"主要驱动因素标识","type":"string"}},"type":"object"},"gmv_breakdown":{"description":"销售额渠道构成","properties":{"live":{"description":"直播销售额字符串","type":"string"},"product_card":{"description":"商品卡销售额字符串","type":"string"},"video":{"description":"视频带货销售额字符串","type":"string"}},"type":"object"},"page_views":{"description":"页面浏览量","type":"integer"},"product_funnels":{"description":"销量领先商品的渠道转化漏斗","items":{"properties":{"channels":{"description":"渠道漏斗列表","items":{"properties":{"channel":{"description":"渠道：video、product_card 或 live","type":"string"},"conversion":{"description":"转化率字符串","type":"string"},"ctr":{"description":"点击率字符串","type":"string"},"gmv":{"description":"销售额字符串","type":"string"},"impressions":{"description":"曝光量","type":"integer"},"page_views":{"description":"页面浏览量","type":"integer"}},"type":"object"},"type":"array"},"name":{"description":"名称","type":"string"},"product_id":{"description":"商品 ID","type":"string"}},"type":"object"},"type":"array"},"underperformers":{"description":"高曝光低转化商品列表","items":{"properties":{"conversion":{"description":"转化率字符串","type":"string"},"impressions":{"description":"曝光量","type":"integer"},"name":{"description":"名称","type":"string"},"note":{"description":"指标说明","type":"string"},"product_id":{"description":"商品 ID","type":"string"}},"type":"object"},"type":"array"},"video":{"description":"视频带货指标","properties":{"count":{"description":"数量","type":"integer"},"gmv":{"description":"销售额字符串","type":"string"},"latest_post_time":{"description":"最近发布时间","type":"string"},"views":{"description":"播放量","type":"integer"}},"type":"object"},"visitors":{"description":"访客数；趋势点中 -1 表示尚无数据，0 表示零访客","type":"integer"}},"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":{"properties":{"gmv":{"description":"销售额字符串","type":"string"},"image":{"description":"商品主图 URL","type":"string"},"images":{"description":"商品主图 URL 列表","items":{"type":"string"},"type":"array"},"items":{"description":"售出件数","type":"integer"},"name":{"description":"名称","type":"string"},"product_id":{"description":"商品 ID","type":"string"},"sale_price":{"description":"代表性单件售价字符串","type":"string"},"stock_alert":{"description":"库存告急提示，无告警时为空","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"battle_date":{"description":"战报口径日期","type":"string"},"risk":{"description":"店铺风险板块（资质/商品状态/退款率/结算），无风险时为空","nullable":true,"properties":{"items":{"description":"风险项目列表，空列表表示无风险项目","items":{"properties":{"action_hint":{"description":"建议采取的操作","type":"string"},"category":{"description":"风险类别：qualification、product_status、refund_rate 或 settlement","type":"string"},"detail":{"description":"风险详情","type":"string"},"level":{"description":"风险级别：critical 或 warning","type":"string"},"title":{"description":"风险标题","type":"string"}},"type":"object"},"type":"array"},"unavailable_note":{"description":"无法提供的风险维度说明列表","items":{"type":"string"},"type":"array"}},"type":"object"},"shop_name":{"description":"店铺名称","type":"string"},"signals":{"description":"退货与库存信号","properties":{"inventory":{"description":"昨日有售商品的库存状况（总库存/最少 SKU 库存/断货 SKU 数/约 X 天售罄预估）","items":{"properties":{"days_left":{"description":"预计售罄天数；昨日无销量时为空","type":"string"},"min_sku_qty":{"description":"最少的单个 SKU 库存","type":"integer"},"name":{"description":"名称","type":"string"},"oos_sku_count":{"description":"缺货 SKU 数量","type":"integer"},"product_id":{"description":"商品 ID","type":"string"},"recent_sold":{"description":"昨日售出件数","type":"integer"},"sku_count":{"description":"SKU 总数量","type":"integer"},"total_qty":{"description":"全部 SKU 库存合计","type":"integer"}},"type":"object"},"type":"array"},"refunds":{"description":"按 SKU 聚合的退货（含最常见退货原因）","items":{"properties":{"count":{"description":"数量","type":"integer"},"seller_sku":{"description":"卖家自定义 SKU","type":"string"},"top_reason":{"description":"最常见退货原因","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"trend":{"description":"近 7 天 GMV 与访客趋势（含连涨/连跌标注）。访客为 -1 表示该日数据未出","nullable":true,"properties":{"gmv_streak":{"description":"销售额连续上涨或下跌提示","type":"string"},"points":{"description":"近 7 天趋势点","items":{"properties":{"date":{"description":"日期","type":"string"},"gmv":{"description":"销售额字符串","type":"string"},"visitors":{"description":"访客数；趋势点中 -1 表示尚无数据，0 表示零访客","type":"integer"}},"type":"object"},"type":"array"}},"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":"RESOURCE_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/orders/detail":{"post":{"description":"批量查询单个已绑定 TikTok Shop Seller 店铺的订单精简详情。每次传入 1–50 个不透明订单 ID；仅返回 TikTok 实际找到且属于请求集合的订单，顺序以 TikTok 返回顺序为准。响应只包含白名单字段，可选返回买家昵称，不包含收件地址、电话、邮箱、物流、优惠明细等完整履约信息。需要有效店铺授权及 seller.order.info 权限。","operationId":"chuhaijiang-seller-orders-detail","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"order_ids":{"description":"要查询的订单 ID 列表，每次 1–50 个且不得重复。订单 ID 按不透明字符串处理，不能包含逗号、Unicode 空白或 ASCII 控制字符。","items":{"description":"TikTok Shop 不透明订单 ID。","minLength":1,"type":"string"},"maxItems":50,"minItems":1,"type":"array","uniqueItems":true},"platform_account_id":{"description":"已绑定且当前用户或团队可访问的 TikTok Shop Seller 平台账号 ID；账号必须处于有效授权状态并具备 seller.order.info 权限。","format":"int64","maximum":2147483647,"minimum":1,"type":"integer"}},"required":["platform_account_id","order_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"orders":[]},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"additionalProperties":false,"properties":{"orders":{"description":"TikTok 实际找到且属于请求集合的订单子集，保持 TikTok 返回顺序；未找到的 ID 不产生占位项，无结果时返回空数组。","items":{"additionalProperties":false,"description":"订单白名单字段。","properties":{"buyer_nickname":{"description":"买家昵称；仅批量精简详情接口允许返回，TikTok 未提供时省略。不得将其视为买家实名。","type":"string"},"create_time":{"description":"订单创建时间，Unix 秒级时间戳。","format":"int64","type":"integer"},"id":{"description":"TikTok Shop 订单 ID。","type":"string"},"is_sample_order":{"description":"是否为样品订单；TikTok 未返回时省略。","type":"boolean"},"line_items":{"description":"订单中的商品与 SKU 白名单信息；无数据时返回空数组。","items":{"additionalProperties":false,"description":"订单商品与 SKU 白名单字段。","properties":{"id":{"description":"订单行项目 ID。","type":"string"},"product_id":{"description":"TikTok Shop 商品 ID。","type":"string"},"product_name":{"description":"商品名称；上游缺失时可能为空字符串。","type":"string"},"sale_price":{"description":"TikTok Shop 返回的商品销售价格字符串。","type":"string"},"seller_sku":{"description":"卖家自定义 SKU；上游缺失时可能为空字符串。","type":"string"},"sku_id":{"description":"TikTok Shop SKU ID。","type":"string"},"sku_image":{"description":"SKU 图片地址；上游缺失时可能为空字符串。","type":"string"},"sku_name":{"description":"SKU 名称；上游缺失时可能为空字符串。","type":"string"}},"required":["id","product_id","product_name","sku_id","sku_name","seller_sku","sku_image","sale_price"],"type":"object"},"type":"array"},"payment":{"additionalProperties":false,"description":"TikTok Shop 返回的精简支付金额字段；金额均为字符串，各字段口径可能因市场而异。","properties":{"currency":{"description":"金额币种代码。","type":"string"},"sub_total":{"description":"TikTok Shop 返回的订单小计字符串；具体口径可能随市场而异。","type":"string"},"tax":{"description":"TikTok Shop 返回的税费字符串。","type":"string"},"total_amount":{"description":"TikTok Shop 返回的订单总金额字符串；不承诺跨市场固定计算公式。","type":"string"}},"required":["currency","total_amount","sub_total","tax"],"type":"object"},"status":{"description":"TikTok Shop 返回的订单状态。","type":"string"},"update_time":{"description":"订单更新时间，Unix 秒级时间戳。","format":"int64","type":"integer"}},"required":["id","status","create_time","update_time","line_items"],"type":"object"},"type":"array"}},"required":["orders"],"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"examples":{"BAD_REQUEST":{"summary":"BAD_REQUEST","value":{"code":"BAD_REQUEST","message":"Backend request rejected.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"请求参数、店铺账号访问条件或 TikTok Shop 请求不满足接口要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"Backend service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"订单服务或上游 TikTok Shop 服务异常；本次调用失败，可稍后重试。"},"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/orders/search":{"post":{"description":"搜索单个已绑定 TikTok Shop Seller 店铺的订单。支持按订单状态筛选和游标分页，结果固定按创建时间倒序；仅返回订单、支付及商品 SKU 的白名单字段，不包含买家昵称、收件地址、电话、邮箱等个人敏感信息。数据来自 TikTok Shop 实时订单接口，需要有效店铺授权及 seller.order.info 权限。","operationId":"chuhaijiang-seller-orders-search","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"order_status":{"description":"可选订单状态筛选。当前 TikTok Shop 常见状态包括 UNPAID、ON_HOLD、AWAITING_SHIPMENT、PARTIALLY_SHIPPING、AWAITING_COLLECTION、IN_TRANSIT、DELIVERED、COMPLETED、CANCELLED；未识别的值可能被 TikTok 拒绝。","type":"string"},"page_size":{"default":20,"description":"每页订单数量，范围 1–50，默认 20。","format":"int32","maximum":50,"minimum":1,"type":"integer"},"page_token":{"description":"上一页响应返回的不透明分页令牌；首次请求不传。不要解析或修改该值。","type":"string"},"platform_account_id":{"description":"已绑定且当前用户或团队可访问的 TikTok Shop Seller 平台账号 ID；账号必须处于有效授权状态并具备 seller.order.info 权限。","format":"int64","maximum":2147483647,"minimum":1,"type":"integer"}},"required":["platform_account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":false,"properties":{"next_page_token":{"description":"下一页不透明分页令牌；没有下一页时为空字符串。","type":"string"},"orders":{"description":"当前页订单，固定按创建时间倒序；无结果时返回空数组。","items":{"additionalProperties":false,"description":"订单白名单字段。","properties":{"create_time":{"description":"订单创建时间，Unix 秒级时间戳。","format":"int64","type":"integer"},"id":{"description":"TikTok Shop 订单 ID。","type":"string"},"is_sample_order":{"description":"是否为样品订单；TikTok 未返回时省略。","type":"boolean"},"line_items":{"description":"订单中的商品与 SKU 白名单信息；无数据时返回空数组。","items":{"additionalProperties":false,"description":"订单商品与 SKU 白名单字段。","properties":{"id":{"description":"订单行项目 ID。","type":"string"},"product_id":{"description":"TikTok Shop 商品 ID。","type":"string"},"product_name":{"description":"商品名称；上游缺失时可能为空字符串。","type":"string"},"sale_price":{"description":"TikTok Shop 返回的商品销售价格字符串。","type":"string"},"seller_sku":{"description":"卖家自定义 SKU；上游缺失时可能为空字符串。","type":"string"},"sku_id":{"description":"TikTok Shop SKU ID。","type":"string"},"sku_image":{"description":"SKU 图片地址；上游缺失时可能为空字符串。","type":"string"},"sku_name":{"description":"SKU 名称；上游缺失时可能为空字符串。","type":"string"}},"required":["id","product_id","product_name","sku_id","sku_name","seller_sku","sku_image","sale_price"],"type":"object"},"type":"array"},"payment":{"additionalProperties":false,"description":"TikTok Shop 返回的精简支付金额字段；金额均为字符串，各字段口径可能因市场而异。","properties":{"currency":{"description":"金额币种代码。","type":"string"},"sub_total":{"description":"TikTok Shop 返回的订单小计字符串；具体口径可能随市场而异。","type":"string"},"tax":{"description":"TikTok Shop 返回的税费字符串。","type":"string"},"total_amount":{"description":"TikTok Shop 返回的订单总金额字符串；不承诺跨市场固定计算公式。","type":"string"}},"required":["currency","total_amount","sub_total","tax"],"type":"object"},"status":{"description":"TikTok Shop 返回的订单状态。","type":"string"},"update_time":{"description":"订单更新时间，Unix 秒级时间戳。","format":"int64","type":"integer"}},"required":["id","status","create_time","update_time","line_items"],"type":"object"},"type":"array"},"total_count":{"description":"TikTok Shop 返回的匹配订单总数。","format":"int32","type":"integer"}},"required":["orders","total_count","next_page_token"],"type":"object"},"request_id":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageInfo"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"examples":{"BAD_REQUEST":{"summary":"BAD_REQUEST","value":{"code":"BAD_REQUEST","message":"Backend request rejected.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"请求参数、店铺账号访问条件或 TikTok Shop 请求不满足接口要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"Backend service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"订单服务或上游 TikTok Shop 服务异常；本次调用失败，可稍后重试。"},"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":{"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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":"查询已绑定的 TikTok Shop Seller 店铺账号及经营概览。`shops` 数组可作为店铺账号列表使用，返回店铺账号 ID、名称、区域、授权状态及经营指标；完成 Seller 授权后，可通过本接口查看已绑定店铺。同时提供多店汇总 GMV/订单/售出件数（含环比）、视频播放与 GPM、日均访客与转化率，以及每个店铺的每日 GMV 序列。数据来自 TikTok Shop 卖家官方接口，statistics 数据有 1-2 天延迟（以 `data_available_date` 为准）。","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":999.9,"credits_cost":0.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":"RESOURCE_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/affiliate/products/search":{"post":{"description":"以指定 TikTok Shop 达人账号搜索选品广场的开放合作商品。","operationId":"chuhaijiang-social-tiktok-shop-affiliate-products-search","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","example":123,"minimum":1,"type":"integer"},"category_id":{"description":"TikTok Shop 类目 ID","type":"string"},"commission_rate_range":{"description":"佣金率筛选，单位为万分比","properties":{"rate_ge":{"description":"最低佣金率（含）；1000 表示 10%","minimum":0,"type":"integer"}},"type":"object"},"page_size":{"default":20,"description":"每页条数，范围 1-20，默认 20。","maximum":20,"minimum":1,"type":"integer"},"page_token":{"description":"翻页 Token，首次请求不传。","type":"string"},"sales_price_range":{"description":"销售价格区间","properties":{"amount_ge":{"description":"最低金额（含）","type":"string"},"amount_lt":{"description":"最高金额（不含）","type":"string"}},"type":"object"},"sort_field":{"description":"排序字段","enum":["commission_rate","product_sales_price","commission","units_sold"],"type":"string"},"sort_order":{"description":"排序方向","enum":["ASC","DESC"],"type":"string"},"title_keywords":{"description":"商品标题关键词，最多 20 个；多个关键词之间为 AND 关系。","items":{"minLength":1,"type":"string"},"maxItems":20,"type":"array"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"next_page_token":{"description":"下一页 Token，为空表示没有更多结果。","type":"string"},"products":{"description":"选品广场商品列表","items":{"properties":{"category_chains":{"description":"商品类目链","items":{"properties":{"id":{"description":"类目 ID","type":"string"},"is_leaf":{"description":"是否叶子类目","type":"boolean"},"local_name":{"description":"类目本地化名称","type":"string"},"parent_id":{"description":"父类目 ID","type":"string"}},"type":"object"},"type":"array"},"commission":{"description":"佣金信息","properties":{"amount":{"description":"每单佣金金额","type":"string"},"currency":{"description":"货币代码","type":"string"},"rate":{"description":"佣金率，万分比整数；1000 表示 10%","type":"integer"}},"type":"object"},"detail_link":{"description":"商品详情链接","type":"string"},"has_inventory":{"description":"是否有库存","type":"boolean"},"id":{"description":"商品 ID","type":"string"},"main_image_url":{"description":"主图 URL","type":"string"},"original_price":{"description":"价格区间","properties":{"currency":{"description":"货币代码","type":"string"},"maximum_amount":{"description":"最高金额","type":"string"},"minimum_amount":{"description":"最低金额","type":"string"}},"type":"object"},"sale_region":{"description":"销售区域","type":"string"},"shop_name":{"description":"店铺名称","type":"string"},"title":{"description":"商品标题","type":"string"},"units_sold":{"description":"销量","format":"int64","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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid TikTok Shop request.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 请求参数、账号归属或账号能力不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok Shop service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 或内部依赖未能完成请求。"},"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":1,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/tiktok-shop/auth-url":{"get":{"description":"生成 TikTok Shop 挂车发布账号授权链接，用于绑定“用来发带货内容的 TikTok 账号”。支持普通带货达人号、店铺官方号和店铺营销号；绑定后都统一作为 `tiktok-shop-pc` 账号，显示在「社媒 → 账号 → TikTok Shop」列表。\n\n本接口不能绑定 TikTok Seller Center 里的店铺主体，也不能用于获取店铺订单、GMV、商品和经营数据。Seller 店铺需要使用另一套卖家授权，绑定后属于 `tiktok-shop-seller`，显示在「资产 → 店铺」。\n\n`type` 只用于选择授权应用的区域档位，不决定绑定的是达人号、店铺官方号还是店铺营销号；不传时默认 `cross-border`。\n\n将返回的 `auth_url` 发送给账号持有人，在任意浏览器打开并登录确认授权。只有授权完成、页面成功跳转至出海匠回调且系统保存账号后，才算绑定成功。本接口目前不返回单次绑定状态；请稍后调用「社媒账号列表」并通过 `platforms=tiktok-shop-pc` 筛选新绑定的账号。\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":"RESOURCE_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/music/search":{"post":{"description":"使用目标 TikTok Shop 账号授权搜索电商音乐库，供挂车视频和图文选曲。将返回 music[].id 用于发布配置 platform_config.music_id；不可与普通 TikTok Business 热门音乐搜索的 song_clip_id 混用。","operationId":"chuhaijiang-social-tiktok-shop-music-search","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"搜索音乐的关键词。","minLength":1,"type":"string"},"language":{"description":"搜索语言，透传 TikTok Shop；不传时由平台决定。","type":"string"},"page_size":{"default":20,"description":"每页返回条数，默认 20；实际限制以 TikTok Shop 返回为准。","minimum":1,"type":"integer"},"page_token":{"description":"分页游标；首次请求不传，翻页传上次响应的 next_page_token。","type":"string"},"platform_account_id":{"description":"当前用户有权访问的 TikTok Shop PC 平台账号 ID；使用该账号授权搜索电商音乐。","minimum":1,"type":"integer"},"region":{"description":"搜索地区，透传 TikTok Shop；不传时由平台决定。","type":"string"},"search_id":{"description":"搜索会话 ID；首次请求不传，翻页沿用上次响应的 search_id，并保持账号和关键词一致。","type":"string"}},"required":["platform_account_id","keyword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.2}},"schema":{"properties":{"data":{"properties":{"has_more":{"description":"是否还有更多搜索结果。","type":"boolean"},"music":{"description":"TikTok Shop 电商授权音乐列表。","items":{"properties":{"author":{"description":"音乐作者。","type":"string"},"cover_urls":{"description":"音乐封面地址列表。","items":{"type":"string"},"type":"array"},"duration":{"description":"音乐时长，保留 TikTok Shop 返回的字符串格式。","type":"string"},"id":{"description":"音乐 ID；选中后用于同一目标账号挂车视频或图文发布的 platform_config.music_id，与普通 TikTok Business 的 song_clip_id 不混用。","type":"string"},"play_urls":{"description":"音乐试听地址列表。","items":{"type":"string"},"type":"array"},"title":{"description":"音乐名称。","type":"string"}},"type":"object"},"type":"array"},"next_page_token":{"description":"下一页游标，翻页时作为 page_token 传入。","type":"string"},"search_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":"RESOURCE_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":["社媒管理/7.TikTok Shop"],"x-billing-mode":"per_call","x-coin-cost":2,"x-scope":"chuhaijiang.social.read"}},"/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","example":123,"minimum":1,"type":"integer"},"data_source":{"description":"数据来源。不传时达人号使用 showcase，官方号和营销号使用 shop；官方号和营销号可显式选择 showcase，达人号不支持 shop。","enum":["shop","showcase"],"type":"string"},"origin":{"default":"SHOWCASE","description":"商品来源筛选，仅在 data_source=showcase 时生效。","enum":["LIVE","SHOWCASE"],"type":"string"},"page_size":{"default":20,"description":"返回商品数量，范围 1-100，默认 20。","maximum":100,"minimum":1,"type":"integer"},"page_token":{"description":"翻页 Token。首次不传，后续传入上一次响应的 next_page_token。","type":"string"},"sort_field":{"description":"排序字段，仅对 shop 数据源生效。","enum":["PRODUCT_ID","PRICE","SALE"],"type":"string"},"sort_order":{"description":"排序方向，仅对 shop 数据源生效。","enum":["DESC","ASC"],"type":"string"},"title_keyword":{"description":"店铺商品按标题搜索；橱窗商品支持标题包含匹配或商品 ID 精确匹配。","type":"string"}},"required":["account_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"creator_type":{"description":"TikTok Shop 创作者账号类型","type":"string"},"data_source":{"description":"实际使用的数据来源：shop 或 showcase","type":"string"},"next_page_token":{"description":"下一页 Token，为空表示没有更多结果。","type":"string"},"products":{"description":"商品列表","items":{"properties":{"added_status":{"description":"橱窗添加状态","type":"string"},"brand_name":{"description":"品牌名称","type":"string"},"collaboration":{"description":"合作信息","properties":{"id":{"description":"合作 ID","type":"string"},"partner_id":{"description":"合作方 ID","type":"string"},"partner_name":{"description":"合作方名称","type":"string"},"type":{"description":"合作类型，如 OPEN","type":"string"}},"type":"object"},"commission":{"description":"佣金比例，单位为万分比","properties":{"rate":{"description":"佣金率，万分比整数；3000 表示 30%","type":"integer"},"reward_rate":{"description":"奖励佣金率，万分比整数；500 表示 5%","type":"integer"}},"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"},"original_price":{"description":"价格区间","properties":{"currency":{"description":"货币代码","type":"string"},"maximum_amount":{"description":"最高金额","type":"string"},"minimum_amount":{"description":"最低金额","type":"string"}},"type":"object"},"platform_discount_price":{"description":"价格区间","properties":{"currency":{"description":"货币代码","type":"string"},"maximum_amount":{"description":"最高金额","type":"string"},"minimum_amount":{"description":"最低金额","type":"string"}},"type":"object"},"seller_discount_price":{"description":"价格区间","properties":{"currency":{"description":"货币代码","type":"string"},"maximum_amount":{"description":"最高金额","type":"string"},"minimum_amount":{"description":"最低金额","type":"string"}},"type":"object"}},"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"},"third_party_link":{"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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid TikTok Shop request.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 请求参数、账号归属或账号能力不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok Shop service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 或内部依赖未能完成请求。"},"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":{"oneOf":[{"properties":{"add_type":{"description":"按商品 ID 添加","enum":["PRODUCT_ID"]}},"required":["product_ids"]},{"properties":{"add_type":{"description":"按商品链接添加","enum":["PRODUCT_LINK"]}},"required":["product_link"]}],"properties":{"account_id":{"description":"当前用户拥有的 TikTok Shop 平台账号 ID","example":123,"minimum":1,"type":"integer"},"add_type":{"description":"添加方式","enum":["PRODUCT_ID","PRODUCT_LINK"],"type":"string"},"product_ids":{"description":"商品 ID 列表。add_type=PRODUCT_ID 时必填，最多 20 个。","items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"product_link":{"description":"商品链接。add_type=PRODUCT_LINK 时必填。","minLength":1,"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":999.9,"credits_cost":0.2}},"schema":{"properties":{"data":{"properties":{"errors":{"description":"逐商品失败列表。null 或空数组表示全部成功；HTTP 请求成功时仍需检查此字段。","items":{"properties":{"code":{"description":"TikTok 错误代码","type":"integer"},"message":{"description":"失败原因","type":"string"},"product_id":{"description":"添加失败的商品 ID","type":"string"}},"type":"object"},"nullable":true,"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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid TikTok Shop request.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 请求参数、账号归属或账号能力不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok Shop service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 或内部依赖未能完成请求。"},"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-shop/showcase/remove":{"post":{"description":"从指定 TikTok Shop 账号的橱窗中移出商品。","operationId":"chuhaijiang-social-tiktok-shop-showcase-remove","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","example":123,"minimum":1,"type":"integer"},"product_ids":{"description":"要移出橱窗的商品 ID，最多 200 个。","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["account_id","product_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.2}},"schema":{"properties":{"data":{"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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid TikTok Shop request.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 请求参数、账号归属或账号能力不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok Shop service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 或内部依赖未能完成请求。"},"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-shop/showcase/top":{"post":{"description":"按传入顺序将商品置顶到指定 TikTok Shop 账号的橱窗。","operationId":"chuhaijiang-social-tiktok-shop-showcase-top","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","example":123,"minimum":1,"type":"integer"},"product_ids":{"description":"要置顶的商品 ID，最多 20 个；数组顺序即目标展示顺序。","items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"required":["account_id","product_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.2}},"schema":{"properties":{"data":{"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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid TikTok Shop request.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 请求参数、账号归属或账号能力不符合要求。"},"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":"RESOURCE_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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"TikTok Shop service returned an error.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"TikTok Shop 或内部依赖未能完成请求。"},"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 账号持有人，在任意浏览器打开并登录确认授权后，该账号会自动绑定到您的团队。可使用同一响应中的 `ref` 调用「查询社媒授权绑定状态」接口（历史兼容路径 `POST /open/v1/social/tiktok/bind-status`），轮询至 `status=bound`；也可稍后调用「社媒账号列表」查看新绑定的账号。\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":"RESOURCE_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、Facebook 或 Instagram 授权链接返回的 ref 查询 OAuth 绑定回执。该接口沿用历史兼容路径 /open/v1/social/tiktok/bind-status，三平台共用。绑定成功返回账号信息；尚未授权、ref 未知、回执过期或 Redis best-effort 写入失败均返回 pending。Facebook 一次授权可能绑定多个具有发布权限的 Page，本接口仅返回首个成功绑定的 Page；完整账号列表请调用「社媒账号列表」。建议轮询间隔不低于 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、Facebook 或 Instagram 授权链接接口获得的授权回执标识；必须原样传入。","type":"string","x-notes":["ref 是不透明的关联标识，不是任何平台的账号 ID。","可从 GET /open/v1/social/tiktok/auth-url、GET /open/v1/social/facebook/auth-url 或 GET /open/v1/social/instagram/auth-url 的成功响应取得；不要自行生成、修改或拼接。","查询接口沿用历史兼容路径 POST /open/v1/social/tiktok/bind-status，TikTok、Facebook、Instagram 共用。"]}},"required":["ref"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"account":{"description":"本次授权绑定的社媒账号信息；仅在 status 为 bound 时返回。Facebook 的单个 account 仅代表首个成功绑定的 Page。","properties":{"account_id":{"description":"出海匠内部账号 ID（platform_accounts.id），发布时请使用此整数 ID。","type":"integer"},"display_name":{"description":"账号或 Facebook Page 的展示名称。","type":"string"},"platform":{"description":"本次绑定的社媒平台。","enum":["tiktok","facebook","instagram"],"type":"string"},"platform_account_id":{"description":"平台侧账号 ID（TikTok openID、Instagram 用户 ID 或 Facebook Page ID），仅用于识别绑定结果；发布时请使用 account_id。","type":"string"},"username":{"description":"账号用户名或 Handle；Facebook Page 没有独立 Handle 时可能返回 Page 名称。","type":"string"}},"required":["platform","username","display_name","platform_account_id","account_id"],"type":"object","x-notes":["pending 状态不会返回 account；请仅在 bound 状态下读取其中字段。","一次 Facebook 授权可能绑定多个具有发布权限的 Page，本接口只返回首个成功绑定的 Page；如需查看全部已绑定账号，请调用社媒账号列表。"]},"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":"授权绑定回执状态：pending 表示当前没有可用回执；bound 表示绑定成功并返回 account。","enum":["pending","bound"],"type":"string","x-notes":["pending 可能表示尚未完成授权、ref 未知、回执已过期或 Redis best-effort 写入失败，不能据此区分具体原因。"]}},"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":"RESOURCE_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":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/posts/spark-authorization-code":{"post":{"description":"为当前用户可访问的 TikTok Business 账号自有帖子生成 Spark Ads 投流授权码。账号须已绑定且有效，并已授予 biz.spark.auth。已有有效授权码会直接复用；已过期授权码会删除后重建。本接口不执行广告主绑定。status_confirmed=false 时可调用「社媒管理/3.视频管理」下「查询 TikTok 投流授权码」确认状态。","operationId":"chuhaijiang-social-tiktok-spark-authorization-code","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"authorization_days":{"default":30,"description":"授权天数，支持 7、30、60、180、365；省略或传 0 时使用 30。已有有效授权码会直接复用，实际期限以返回值为准。","enum":[0,7,30,60,180,365],"format":"int32","type":"integer"},"item_id":{"description":"该 TikTok 账号自己的帖子 ID；来自「社媒管理/3.视频管理」下「发布记录列表」返回的 platform_video_id。","minLength":1,"type":"string"},"platform_account_id":{"description":"已绑定且当前用户可访问的 TikTok Business 账号 ID，来自「社媒管理/1.账号管理」下「社媒账号列表」返回的 id；账号须有效且已授予 biz.spark.auth 权限。","format":"int32","minimum":1,"type":"integer"}},"required":["platform_account_id","item_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"auth_code_status":""},"request_id":"req_abc123","usage":{"credits_balance":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"auth_code":{"description":"用于 Spark Ads 投流的帖子授权码；查询未取得授权码时为空字符串。","type":"string"},"auth_code_end_time":{"description":"授权结束时间，Unix 秒级时间戳；未取得时为 0。","format":"int64","type":"integer"},"auth_code_start_time":{"description":"授权开始时间，Unix 秒级时间戳；未取得时为 0。","format":"int64","type":"integer"},"auth_code_status":{"description":"授权码状态：NOT_USED 未使用、IN_USE 使用中、EXPIRED 已过期；未确认或未取得时为空字符串。","enum":["","NOT_USED","IN_USE","EXPIRED"],"type":"string"},"authorization_days":{"description":"授权天数；生成接口在上游未返回天数时使用请求天数，查询未取得时为 0。","format":"int32","type":"integer"},"item_id":{"description":"TikTok 帖子 ID。","type":"string"},"status_confirmed":{"description":"是否已通过 TikTok 状态查询确认同一帖子、同一授权码；生成后尚未确认或查询未取得授权码时为 false，查询取得授权码时为 true。","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":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid social API request. Review the request parameters against the endpoint documentation.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"请求参数无效，或帖子不属于所选 TikTok 账号。"},"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":{"examples":{"FORBIDDEN":{"summary":"FORBIDDEN","value":{"code":"FORBIDDEN","message":"The connected platform account lacks a required permission. Review the granted permissions and reconnect the account if needed.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"账号缺少 biz.spark.auth 权限、授权已失效或账号能力受限，请核对账号授权并重新连接。"},"404":{"content":{"application/json":{"examples":{"RESOURCE_NOT_FOUND":{"summary":"RESOURCE_NOT_FOUND","value":{"code":"RESOURCE_NOT_FOUND","message":"The requested resource was not found. Verify the resource ID and connected platform account.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"指定账号不存在或当前用户无权访问。"},"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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"Social service returned an error. Try again later. If the issue persists, contact support and include the request_id.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"社媒服务或上游依赖异常，可稍后重试。"},"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":["社媒管理/3.视频管理"],"x-billing-mode":"per_call","x-coin-cost":1,"x-scope":"chuhaijiang.social.write"}},"/open/v1/social/tiktok/posts/spark-authorization-code/status":{"post":{"description":"只读查询当前用户可访问的 TikTok Business 账号自有帖子的 Spark Ads 授权码和状态，不生成或修改帖子授权码。账号须已绑定且有效，并已授予 biz.spark.auth。未生成过授权码或 TikTok 状态查询失败时，当前后端均可能成功返回空 auth_code；空值不代表已明确确认不存在授权码。","operationId":"chuhaijiang-social-tiktok-spark-authorization-code-status","parameters":[{"description":"您的 API Key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"item_id":{"description":"该 TikTok 账号自己的帖子 ID；来自「社媒管理/3.视频管理」下「发布记录列表」返回的 platform_video_id。","minLength":1,"type":"string"},"platform_account_id":{"description":"已绑定且当前用户可访问的 TikTok Business 账号 ID，来自「社媒管理/1.账号管理」下「社媒账号列表」返回的 id；账号须有效且已授予 biz.spark.auth 权限。","format":"int32","minimum":1,"type":"integer"}},"required":["platform_account_id","item_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"auth_code_status":""},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"auth_code":{"description":"用于 Spark Ads 投流的帖子授权码；查询未取得授权码时为空字符串。","type":"string"},"auth_code_end_time":{"description":"授权结束时间，Unix 秒级时间戳；未取得时为 0。","format":"int64","type":"integer"},"auth_code_start_time":{"description":"授权开始时间，Unix 秒级时间戳；未取得时为 0。","format":"int64","type":"integer"},"auth_code_status":{"description":"授权码状态：NOT_USED 未使用、IN_USE 使用中、EXPIRED 已过期；未确认或未取得时为空字符串。","enum":["","NOT_USED","IN_USE","EXPIRED"],"type":"string"},"authorization_days":{"description":"授权天数；生成接口在上游未返回天数时使用请求天数，查询未取得时为 0。","format":"int32","type":"integer"},"item_id":{"description":"TikTok 帖子 ID。","type":"string"},"status_confirmed":{"description":"是否已通过 TikTok 状态查询确认同一帖子、同一授权码；生成后尚未确认或查询未取得授权码时为 false，查询取得授权码时为 true。","type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"Successful response"},"400":{"content":{"application/json":{"examples":{"INVALID_PARAM":{"summary":"INVALID_PARAM","value":{"code":"INVALID_PARAM","message":"Invalid social API request. Review the request parameters against the endpoint documentation.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"请求参数无效，或帖子不属于所选 TikTok 账号。"},"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":{"examples":{"FORBIDDEN":{"summary":"FORBIDDEN","value":{"code":"FORBIDDEN","message":"The connected platform account lacks a required permission. Review the granted permissions and reconnect the account if needed.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"账号缺少 biz.spark.auth 权限、授权已失效或账号能力受限，请核对账号授权并重新连接。"},"404":{"content":{"application/json":{"examples":{"RESOURCE_NOT_FOUND":{"summary":"RESOURCE_NOT_FOUND","value":{"code":"RESOURCE_NOT_FOUND","message":"The requested resource was not found. Verify the resource ID and connected platform account.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"指定账号不存在或当前用户无权访问。"},"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":{"examples":{"BACKEND_ERROR":{"summary":"BACKEND_ERROR","value":{"code":"BACKEND_ERROR","message":"Social service returned an error. Try again later. If the issue persists, contact support and include the request_id.","request_id":"req_example"}}},"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"社媒服务或上游依赖异常，可稍后重试。"},"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":["社媒管理/3.视频管理"],"x-billing-mode":"free","x-coin-cost":0,"x-scope":"chuhaijiang.social.read"}},"/open/v1/social/tiktok/qrcode":{"post":{"description":"获取 TikTok 扫码登录所需的授权链接和扫码会话 Token。调用方需将返回的授权链接转换为二维码并展示给用户扫码。\n\n⚠️ 重要：获取授权链接后必须立即开始轮询「TikTok扫码状态查询」接口（每2~3秒，直到返回 status=confirmed/utilised），不要等扫码后才开始轮询——从未被查询过状态的二维码，扫码时会直接提示二维码已过期。\n\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":"连接器标识，固定传 \"trenz\"","enum":["trenz"],"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":"用于生成二维码的 TikTok 授权链接（通常以 aweme:// 开头），不是二维码图片地址。调用方需将该链接转换为二维码图片或 SVG，展示给用户使用 TikTok App 扫码。为保证清晰度，建议生成尺寸不低于 384×384 像素，避免放大、压缩或使用 JPG 格式。","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":"RESOURCE_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":"连接器标识，固定传 \"trenz\"","enum":["trenz"],"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":0.1}},"schema":{"properties":{"data":{"properties":{"platform_rules":{"additionalProperties":{"properties":{"duration":{"description":"时长限制，秒","properties":{"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"}},"type":"object"},"file_size":{"description":"文件大小限制，字节","properties":{"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"}},"type":"object"},"frame_rate":{"description":"帧率限制，帧/秒","properties":{"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"}},"type":"object"},"height":{"description":"高度限制，像素","properties":{"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"}},"type":"object"},"width":{"description":"宽度限制，像素","properties":{"max":{"description":"最大值","type":"number"},"min":{"description":"最小值","type":"number"}},"type":"object"}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1}},"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":"RESOURCE_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":999.9,"credits_cost":0.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"},"unread_comment_count":{"description":"该视频未读且未删除的评论数。","format":"int64","minimum":0,"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":"RESOURCE_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":"查询异步任务的执行状态和结果。任务可能处于 running、success、failed 或 refunded；仅 success 返回 result。\n\n### 查看任务结果\n\n任务成功后，选择你提交任务时使用的接口，查看对应返回字段和示例。\n\n在 **Responses → 200** 中选择 **任务成功**，展开 `data.result`，按接口名称查看返回字段；在右侧 **Example Responses** 中选择同名接口，查看完整响应示例。","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":{"examples":{"running":{"summary":"任务执行中","value":{"data":{"status":"running","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-gpt-image-2-generate":{"summary":"GPT-Image-2 图片生成 成功","value":{"data":{"result":{"image_size":"2K","os_url":"https://oss-media.chuhaijiang.com/ai-image/generated/example.png?sign=example","ratio":"1:1","task_status":"finished"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-happyhorse-generate":{"summary":"HappyHorse 1.1 视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-nanobanana-generate":{"summary":"Nanobanana 图片生成 成功","value":{"data":{"result":{"image_size":"2K","os_url":"https://oss-media.chuhaijiang.com/ai-image/generated/example.png?sign=example","ratio":"1:1","task_status":"finished"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-sd-pro-fast-generate":{"summary":"SeeDance2.0 Pro Fast视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-sd-pro-generate":{"summary":"SeeDance2.0 Pro视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-seedance-2-5-generate":{"summary":"Seedance 2.5 视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-veo3-generate":{"summary":"Veo 3.1 视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-wan26-generate":{"summary":"Wan2.6视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-ai-wan30-generate":{"summary":"Wan 3.0 视频生成 成功","value":{"data":{"result":{"cover_url":"https://oss-media.chuhaijiang.com/ai-video/covers/example.jpg?sign=example","gen_id":"gen_example_123","task_status":"finished","video_duration":5,"video_url":"https://oss-media.chuhaijiang.com/ai-video/generated/example.mp4?sign=example"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-product-review-analysis":{"summary":"产品评论分析 成功","value":{"data":{"result":{"entity_list":[{"entity_id":"review_123456","field_list":[{"field_key":"tiktok_product_detail_review_content","field_type":"text","value":"The color lasts all day and does not feel dry."},{"field_key":"tiktok_product_detail_review_rating","field_type":"number","value":5},{"field_key":"tiktok_product_detail_review_opinions","field_type":"opinions","value":[{"emotion_type":1,"highlight":["lasts all day","does not feel dry"],"opinion":"持久且不拔干","opinion_en":"Long-lasting without drying","opinion_type":"使用体验","opinion_type_en":"User experience","opinion_type_zh":"使用体验","opinion_zh":"持久且不拔干","sentiment":0.9}]}],"relate_id":"prod_123456"}],"total_count":1},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-video-scripts-breakdown-v2":{"summary":"视频脚本拆解V2 成功","value":{"data":{"result":{"entity_list":[{"entity_id":"7300000000000000000","field_list":[{"field_key":"tiktok_video_script_breakdown_video_id","field_type":"entity_id","value":"7300000000000000000"},{"field_key":"tiktok_video_script_brekdown_modules_en","field_type":"modules","value":{"actionable_insights":"Keep the product visible in the first three seconds.","business_insight":"The proof-led structure reduces purchase uncertainty.","competitive_analysis":"More direct than feature-only competitor videos.","core_insight":"The opening immediately presents the use case.","created_at":1787889600000,"critical_evaluation":"The call to action could be clearer.","data_validation":"Engagement signals support the identified hook.","detailed_breakdown":"The narrative follows problem, proof, and action.","language":"en","shot_analysis":"Shot 1 introduces the problem; shot 2 demonstrates the solution.","title":"High-converting product demo breakdown","video_basic_info":"A short-form product demonstration."}}]}],"total_count":1},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-chuhaijiang-video-selling-points-analysis":{"summary":"视频卖点可视化分析 成功","value":{"data":{"result":{"content_presentation":[],"hash_tag":[],"pain_point":[],"selling_point":[{"name":"持久防沾杯","normalized_video_total_gmv":31306.35,"proof":["transfer proof","smudge proof"],"top_video_info_list":[{"author_unique_id":"miaava856","country_code":"US","follower_cnt":1550,"follower_count":1550,"normalized_video_total_gmv":7324.9,"share_url":"https://www.tiktok.com/@miaava856/video/7669032905657552142","video_comment_count":5,"video_desc":"One set, two finishes, endless looks – and it actually stays.","video_id":"7669032905657552142","video_like_count":457,"video_play_count":175000,"video_popularity":583,"video_share_count":121,"video_total_gmv":7324.9,"video_total_gpm":41.86}],"video_count":9,"video_id_list":["7669032905657552142"],"video_play_count":9551000,"video_popularity":125895,"video_total_gmv":31306.35,"video_total_gpm":3.28}]},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"success-undeclared":{"summary":"未声明结构的异步任务成功","value":{"data":{"result":{"value":"API-specific result"},"status":"success","task_id":"task_abc123"},"request_id":"req_abc123"}},"terminal-failed":{"summary":"任务失败","value":{"data":{"error_code":"task_failed","error_message":"异步任务执行失败","status":"failed","task_id":"task_abc123"},"request_id":"req_abc123"}},"terminal-refunded":{"summary":"任务失败且已退款","value":{"data":{"error_code":"task_failed","error_message":"异步任务执行失败，消耗已退回","status":"refunded","task_id":"task_abc123"},"request_id":"req_abc123"}}},"schema":{"oneOf":[{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"status":{"description":"任务状态","enum":["running"],"type":"string"},"task_id":{"description":"任务 ID","type":"string"}},"required":["task_id","status"],"title":"任务执行中","type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"title":"任务执行中","type":"object"},{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"result":{"anyOf":[{"properties":{"image_size":{"description":"生成图片规格，例如 1K、2K、4K","type":"string"},"os_url":{"description":"生成图片的可访问 URL","format":"uri","type":"string"},"ratio":{"description":"生成图片宽高比，例如 1:1、9:16","type":"string"},"task_status":{"description":"下游任务完成状态；外层 data.status 才是开放平台统一状态","enum":["finished"],"type":"string"}},"required":["task_status","ratio","image_size"],"title":"AI 图片生成结果","type":"object","x-docs-api-names":["GPT-Image-2 图片生成","Nanobanana 图片生成"]},{"properties":{"cover_url":{"description":"视频封面的可访问 URL；生成封面成功时返回","format":"uri","type":"string"},"gen_id":{"description":"下游生成记录 ID；供应商返回时提供","type":"string"},"task_status":{"description":"下游任务完成状态；外层 data.status 才是开放平台统一状态","enum":["finished"],"type":"string"},"video_duration":{"description":"实际生成视频时长，单位秒","minimum":0,"type":"number"},"video_url":{"description":"生成视频的可访问 URL","format":"uri","type":"string"}},"required":["task_status"],"title":"AI 视频生成结果","type":"object","x-docs-api-names":["HappyHorse 1.1 视频生成","SeeDance2.0 Pro Fast视频生成","SeeDance2.0 Pro视频生成","Seedance 2.5 视频生成","Veo 3.1 视频生成","Wan2.6视频生成","Wan 3.0 视频生成"]},{"properties":{"entity_list":{"description":"已分析的商品评论实体列表","items":{"properties":{"entity_id":{"description":"评论实体 ID","type":"string"},"field_list":{"items":{"properties":{"field_key":{"description":"评论字段标识；具体可见本接口返回示例","type":"string"},"field_type":{"description":"字段渲染类型，例如 entity_id、text、number、datetime、opinions","type":"string"},"value":{"anyOf":[{"description":"文本、ID 或时间展示值","type":"string"},{"description":"评分等数值","type":"number"},{"description":"评论观点列表","items":{"properties":{"emotion_type":{"description":"由情感分值派生的情绪类型：0=负向，1=正向","enum":[0,1],"type":"integer"},"highlight":{"description":"支撑观点的原文高亮短语","items":{"description":"评论原文中的证据短语","type":"string"},"type":"array"},"opinion":{"description":"观点文本","type":"string"},"opinion_en":{"description":"观点英文文本","type":"string"},"opinion_type":{"description":"观点分类","type":"string"},"opinion_type_en":{"description":"观点分类英文文本","type":"string"},"opinion_type_zh":{"description":"观点分类中文文本","type":"string"},"opinion_zh":{"description":"观点中文文本","type":"string"},"sentiment":{"description":"情感分值，越接近 1 越正向","maximum":1,"minimum":0,"type":"number"}},"required":["opinion","sentiment","opinion_type","highlight"],"type":"object"},"type":"array"},{"description":"图片、SKU 等列表字段","items":{},"type":"array"},{"description":"媒体或规格等结构化字段","type":"object"},{"description":"字段在当前评论或历史数据中不存在时返回 null","enum":[null],"nullable":true,"type":"string"}],"description":"字段值；由 field_key 决定类型，opinions 字段为观点数组"}},"required":["field_key","field_type","value"],"type":"object"},"type":"array"},"relate_id":{"description":"关联商品 ID","type":"string"}},"required":["field_list"],"type":"object"},"type":"array"},"total_count":{"description":"命中的评论实体数量","minimum":0,"type":"integer"}},"required":["entity_list","total_count"],"title":"产品评论分析结果","type":"object","x-docs-api-names":["产品评论分析"]},{"properties":{"entity_list":{"description":"视频脚本拆解实体列表","items":{"properties":{"entity_id":{"description":"结果实体 ID，通常为视频 ID","type":"string"},"field_list":{"description":"字段记录列表。视频 ID 记录和拆解报告记录可以同时出现；逐条读取 field_type，再解析对应的 value。","items":{"oneOf":[{"properties":{"field_key":{"description":"字段标识；通过 field_type 判断本条记录的内容类型。","example":"tiktok_video_script_breakdown_video_id","type":"string"},"field_type":{"description":"本条记录的内容类型","enum":["entity_id"],"type":"string"},"value":{"description":"视频 ID 字符串；无对应数据时为 null。","example":"7300000000000000000","nullable":true,"type":"string"}},"required":["field_key","field_type","value"],"title":"视频 ID 记录","type":"object"},{"properties":{"field_key":{"description":"字段标识；通过 field_type 判断本条记录的内容类型。","example":"tiktok_video_script_brekdown_modules_en","type":"string"},"field_type":{"description":"本条记录的内容类型","enum":["modules"],"type":"string"},"value":{"anyOf":[{"properties":{"actionable_insights":{"description":"可执行建议，Markdown 文本","type":"string"},"business_insight":{"description":"商业洞察，Markdown 文本","type":"string"},"competitive_analysis":{"description":"竞争分析，Markdown 文本","type":"string"},"core_insight":{"description":"核心洞察，Markdown 文本","type":"string"},"created_at":{"description":"分析生成时间，Unix 毫秒时间戳","format":"int64","type":"integer"},"critical_evaluation":{"description":"批判性评估，Markdown 文本","type":"string"},"data_validation":{"description":"数据交叉验证，Markdown 文本","type":"string"},"detailed_breakdown":{"description":"详细拆解，Markdown 文本","type":"string"},"language":{"description":"本字段内容语言","enum":["zh","en"],"type":"string"},"reality_validation":{"description":"现实验证；存在 performance_data 时可能返回","type":"string"},"shot_analysis":{"description":"分镜头深度拆解，Markdown 文本","type":"string"},"title":{"description":"拆解报告标题","type":"string"},"video_basic_info":{"description":"视频基础信息，Markdown 文本","type":"string"}},"required":["language","created_at"],"title":"拆解报告内容","type":"object"},{"description":"当前语言或历史数据中没有该字段值时返回 null","enum":[null],"nullable":true,"type":"string"}],"description":"结构化拆解报告；无对应语言或历史数据时为 null。"}},"required":["field_key","field_type","value"],"title":"拆解报告记录","type":"object"}]},"type":"array"},"relate_id":{"description":"关联实体 ID；存在关联关系时返回","type":"string"}},"required":["field_list"],"type":"object"},"type":"array"},"total_count":{"description":"命中的拆解实体数量","minimum":0,"type":"integer"}},"required":["entity_list","total_count"],"title":"视频脚本拆解 V2 结果","type":"object","x-docs-api-names":["视频脚本拆解V2"]},{"description":"卖点、痛点、内容呈现和关键词四类视频聚类结果。每个聚类的 video_id_list 包含全部命中视频；top_video_info_list 仅含代表视频。封面或其他完整视频字段请调用「视频详情」GET /open/v1/videos/{id}。","properties":{"content_presentation":{"description":"内容呈现方式聚类","items":{"description":"一个分析聚类及其证据、覆盖视频和聚合指标。","properties":{"name":{"description":"聚类名称","type":"string"},"normalized_video_total_gmv":{"description":"该聚类归一化后累计 GMV","type":"number"},"proof":{"description":"支撑该聚类的代表性关键词或原文短语，最多 5 条","items":{"type":"string"},"type":"array"},"top_video_info_list":{"description":"按 GMV 排序的代表视频，最多 3 条；不是全部命中视频","items":{"description":"代表视频的基础元数据与聚合指标。封面和其他完整字段请使用 video_id 调用「视频详情」GET /open/v1/videos/{id}。","properties":{"author_unique_id":{"description":"TikTok 作者唯一用户名","type":"string"},"country_code":{"description":"视频所属国家或地区代码","type":"string"},"follower_cnt":{"description":"作者粉丝数（Scout 原始字段）","minimum":0,"type":"integer"},"follower_count":{"description":"作者粉丝数（兼容字段）","minimum":0,"type":"integer"},"normalized_video_total_gmv":{"description":"归一化后的视频累计 GMV","type":"number"},"share_url":{"description":"可直接打开的 TikTok 分享链接；仅在作者标识可用时返回","format":"uri","type":"string"},"video_comment_count":{"description":"视频评论量","minimum":0,"type":"integer"},"video_desc":{"description":"视频文案","type":"string"},"video_id":{"description":"TikTok 视频 ID","type":"string"},"video_like_count":{"description":"视频点赞量","minimum":0,"type":"integer"},"video_play_count":{"description":"视频播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"视频热度（点赞、评论与分享量之和）","minimum":0,"type":"integer"},"video_share_count":{"description":"视频分享量","minimum":0,"type":"integer"},"video_total_gmv":{"description":"视频累计 GMV","type":"number"},"video_total_gpm":{"description":"视频每千次播放 GMV","type":"number"}},"required":["video_id","follower_cnt","follower_count","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity"],"type":"object"},"type":"array"},"video_count":{"description":"命中该聚类的视频数量","minimum":0,"type":"integer"},"video_id_list":{"description":"命中该聚类的全部视频 ID；需要封面或完整详情时逐个调用「视频详情」接口","items":{"type":"string"},"type":"array"},"video_play_count":{"description":"该聚类视频累计播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"该聚类视频累计热度","minimum":0,"type":"integer"},"video_total_gmv":{"description":"该聚类视频累计 GMV","type":"number"},"video_total_gpm":{"description":"该聚类每千次播放 GMV","type":"number"}},"required":["name","proof","video_count","video_id_list","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity","top_video_info_list"],"type":"object"},"type":"array"},"hash_tag":{"description":"Hashtag/关键词聚类","items":{"description":"一个分析聚类及其证据、覆盖视频和聚合指标。","properties":{"name":{"description":"聚类名称","type":"string"},"normalized_video_total_gmv":{"description":"该聚类归一化后累计 GMV","type":"number"},"proof":{"description":"支撑该聚类的代表性关键词或原文短语，最多 5 条","items":{"type":"string"},"type":"array"},"top_video_info_list":{"description":"按 GMV 排序的代表视频，最多 3 条；不是全部命中视频","items":{"description":"代表视频的基础元数据与聚合指标。封面和其他完整字段请使用 video_id 调用「视频详情」GET /open/v1/videos/{id}。","properties":{"author_unique_id":{"description":"TikTok 作者唯一用户名","type":"string"},"country_code":{"description":"视频所属国家或地区代码","type":"string"},"follower_cnt":{"description":"作者粉丝数（Scout 原始字段）","minimum":0,"type":"integer"},"follower_count":{"description":"作者粉丝数（兼容字段）","minimum":0,"type":"integer"},"normalized_video_total_gmv":{"description":"归一化后的视频累计 GMV","type":"number"},"share_url":{"description":"可直接打开的 TikTok 分享链接；仅在作者标识可用时返回","format":"uri","type":"string"},"video_comment_count":{"description":"视频评论量","minimum":0,"type":"integer"},"video_desc":{"description":"视频文案","type":"string"},"video_id":{"description":"TikTok 视频 ID","type":"string"},"video_like_count":{"description":"视频点赞量","minimum":0,"type":"integer"},"video_play_count":{"description":"视频播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"视频热度（点赞、评论与分享量之和）","minimum":0,"type":"integer"},"video_share_count":{"description":"视频分享量","minimum":0,"type":"integer"},"video_total_gmv":{"description":"视频累计 GMV","type":"number"},"video_total_gpm":{"description":"视频每千次播放 GMV","type":"number"}},"required":["video_id","follower_cnt","follower_count","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity"],"type":"object"},"type":"array"},"video_count":{"description":"命中该聚类的视频数量","minimum":0,"type":"integer"},"video_id_list":{"description":"命中该聚类的全部视频 ID；需要封面或完整详情时逐个调用「视频详情」接口","items":{"type":"string"},"type":"array"},"video_play_count":{"description":"该聚类视频累计播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"该聚类视频累计热度","minimum":0,"type":"integer"},"video_total_gmv":{"description":"该聚类视频累计 GMV","type":"number"},"video_total_gpm":{"description":"该聚类每千次播放 GMV","type":"number"}},"required":["name","proof","video_count","video_id_list","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity","top_video_info_list"],"type":"object"},"type":"array"},"pain_point":{"description":"用户痛点聚类","items":{"description":"一个分析聚类及其证据、覆盖视频和聚合指标。","properties":{"name":{"description":"聚类名称","type":"string"},"normalized_video_total_gmv":{"description":"该聚类归一化后累计 GMV","type":"number"},"proof":{"description":"支撑该聚类的代表性关键词或原文短语，最多 5 条","items":{"type":"string"},"type":"array"},"top_video_info_list":{"description":"按 GMV 排序的代表视频，最多 3 条；不是全部命中视频","items":{"description":"代表视频的基础元数据与聚合指标。封面和其他完整字段请使用 video_id 调用「视频详情」GET /open/v1/videos/{id}。","properties":{"author_unique_id":{"description":"TikTok 作者唯一用户名","type":"string"},"country_code":{"description":"视频所属国家或地区代码","type":"string"},"follower_cnt":{"description":"作者粉丝数（Scout 原始字段）","minimum":0,"type":"integer"},"follower_count":{"description":"作者粉丝数（兼容字段）","minimum":0,"type":"integer"},"normalized_video_total_gmv":{"description":"归一化后的视频累计 GMV","type":"number"},"share_url":{"description":"可直接打开的 TikTok 分享链接；仅在作者标识可用时返回","format":"uri","type":"string"},"video_comment_count":{"description":"视频评论量","minimum":0,"type":"integer"},"video_desc":{"description":"视频文案","type":"string"},"video_id":{"description":"TikTok 视频 ID","type":"string"},"video_like_count":{"description":"视频点赞量","minimum":0,"type":"integer"},"video_play_count":{"description":"视频播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"视频热度（点赞、评论与分享量之和）","minimum":0,"type":"integer"},"video_share_count":{"description":"视频分享量","minimum":0,"type":"integer"},"video_total_gmv":{"description":"视频累计 GMV","type":"number"},"video_total_gpm":{"description":"视频每千次播放 GMV","type":"number"}},"required":["video_id","follower_cnt","follower_count","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity"],"type":"object"},"type":"array"},"video_count":{"description":"命中该聚类的视频数量","minimum":0,"type":"integer"},"video_id_list":{"description":"命中该聚类的全部视频 ID；需要封面或完整详情时逐个调用「视频详情」接口","items":{"type":"string"},"type":"array"},"video_play_count":{"description":"该聚类视频累计播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"该聚类视频累计热度","minimum":0,"type":"integer"},"video_total_gmv":{"description":"该聚类视频累计 GMV","type":"number"},"video_total_gpm":{"description":"该聚类每千次播放 GMV","type":"number"}},"required":["name","proof","video_count","video_id_list","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity","top_video_info_list"],"type":"object"},"type":"array"},"selling_point":{"description":"产品卖点聚类","items":{"description":"一个分析聚类及其证据、覆盖视频和聚合指标。","properties":{"name":{"description":"聚类名称","type":"string"},"normalized_video_total_gmv":{"description":"该聚类归一化后累计 GMV","type":"number"},"proof":{"description":"支撑该聚类的代表性关键词或原文短语，最多 5 条","items":{"type":"string"},"type":"array"},"top_video_info_list":{"description":"按 GMV 排序的代表视频，最多 3 条；不是全部命中视频","items":{"description":"代表视频的基础元数据与聚合指标。封面和其他完整字段请使用 video_id 调用「视频详情」GET /open/v1/videos/{id}。","properties":{"author_unique_id":{"description":"TikTok 作者唯一用户名","type":"string"},"country_code":{"description":"视频所属国家或地区代码","type":"string"},"follower_cnt":{"description":"作者粉丝数（Scout 原始字段）","minimum":0,"type":"integer"},"follower_count":{"description":"作者粉丝数（兼容字段）","minimum":0,"type":"integer"},"normalized_video_total_gmv":{"description":"归一化后的视频累计 GMV","type":"number"},"share_url":{"description":"可直接打开的 TikTok 分享链接；仅在作者标识可用时返回","format":"uri","type":"string"},"video_comment_count":{"description":"视频评论量","minimum":0,"type":"integer"},"video_desc":{"description":"视频文案","type":"string"},"video_id":{"description":"TikTok 视频 ID","type":"string"},"video_like_count":{"description":"视频点赞量","minimum":0,"type":"integer"},"video_play_count":{"description":"视频播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"视频热度（点赞、评论与分享量之和）","minimum":0,"type":"integer"},"video_share_count":{"description":"视频分享量","minimum":0,"type":"integer"},"video_total_gmv":{"description":"视频累计 GMV","type":"number"},"video_total_gpm":{"description":"视频每千次播放 GMV","type":"number"}},"required":["video_id","follower_cnt","follower_count","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity"],"type":"object"},"type":"array"},"video_count":{"description":"命中该聚类的视频数量","minimum":0,"type":"integer"},"video_id_list":{"description":"命中该聚类的全部视频 ID；需要封面或完整详情时逐个调用「视频详情」接口","items":{"type":"string"},"type":"array"},"video_play_count":{"description":"该聚类视频累计播放量","minimum":0,"type":"integer"},"video_popularity":{"description":"该聚类视频累计热度","minimum":0,"type":"integer"},"video_total_gmv":{"description":"该聚类视频累计 GMV","type":"number"},"video_total_gpm":{"description":"该聚类每千次播放 GMV","type":"number"}},"required":["name","proof","video_count","video_id_list","video_total_gmv","normalized_video_total_gmv","video_total_gpm","video_play_count","video_popularity","top_video_info_list"],"type":"object"},"type":"array"}},"required":["selling_point","pain_point","content_presentation","hash_tag"],"title":"视频卖点可视化分析结果","type":"object","x-docs-api-names":["视频卖点可视化分析"]},{"description":"兼容尚未声明结果结构的异步接口，可返回任意 JSON 值。","title":"其他异步任务结果（结构未单独声明）"}],"description":"任务成功后，选择你提交任务时使用的接口，查看对应返回字段和示例。","x-docs-union-kind":"task-result"},"status":{"description":"任务状态","enum":["success"],"type":"string"},"task_id":{"description":"任务 ID","type":"string"}},"required":["task_id","status","result"],"title":"任务成功","type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"title":"任务成功","type":"object"},{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"error_code":{"description":"失败错误码（failed 或 refunded 状态下可能返回）","type":"string"},"error_message":{"description":"失败原因（failed 或 refunded 状态下可能返回）","type":"string"},"status":{"description":"任务状态","enum":["failed"],"type":"string"},"task_id":{"description":"任务 ID","type":"string"}},"required":["task_id","status"],"title":"任务失败","type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"title":"任务失败","type":"object"},{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"error_code":{"description":"失败错误码（failed 或 refunded 状态下可能返回）","type":"string"},"error_message":{"description":"失败原因（failed 或 refunded 状态下可能返回）","type":"string"},"status":{"description":"任务状态","enum":["refunded"],"type":"string"},"task_id":{"description":"任务 ID","type":"string"}},"required":["task_id","status"],"title":"任务已退款","type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"title":"任务已退款","type":"object"}],"x-docs-union-kind":"task-status"}}},"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":"RESOURCE_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，用于客户端将文件直接上传到对象存储。\n\n## 与普通版的区别\n\n本接口是加速版，路径为 `/open/v1/upload/presigned-url`，返回 `url`、`os_key`、`os_bucket` 和 `signed_url`。普通版「生成上传预签名URL」路径为 `/open/v1/social/upload/presigned-url`，返回字段名不同。两者都需要再发起一次 HTTP PUT 才会真正上传文件。\n\n## Step 1：获取上传地址\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/upload/presigned-url\"   -H \"X-API-Key: YOUR_API_KEY\"   -H \"Content-Type: application/json\"   -d '{\"file_name\":\"my_video.mp4\"}'\n```\n\n返回示例：\n\n```json\n{\n  \"data\": {\n    \"url\": \"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?...\",\n    \"os_key\": \"upload/abc123.mp4\",\n    \"os_bucket\": \"data-datanebula-object\",\n    \"signed_url\": \"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?...\"\n  }\n}\n```\n\n## Step 2：上传文件\n\n对返回的 `url` 发起 HTTP PUT，请求体必须是文件二进制：\n\n```bash\ncurl -X PUT \"{url}\"   -H \"Content-Type: video/mp4\"   --data-binary @my_video.mp4\n```\n\n`url` 有效期为 180 秒，获取后请立即上传。必须保留 `--data-binary @my_video.mp4` 中的 `@`，并将完整 URL 放在引号中。图片请使用实际 MIME 类型，例如 `image/jpeg` 或 `image/png`。\n\n上传请求返回 HTTP 2xx 后，文件才算上传完成；`signed_url` 是文件的临时访问地址，有效期 24 小时。\n\n## Step 3：传给下游接口\n\n- 「视频信息校验」：`bucket_name = os_bucket`，`object_key = os_key`\n- 「上传并发布视频」：`bucket_name = os_bucket`，`bucket_key = os_key`\n- AI 图片/视频生成接口：可将 `signed_url` 作为需要公网 URL 的参考素材地址\n\n私信媒体文件不使用本接口，请调用「社媒管理/8.私信管理」分类下的「私信上传预签名URL」。","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","example":"my_video.mp4","type":"string"}},"required":["file_name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"data":{"os_bucket":"data-datanebula-object","os_key":"upload/abc123.mp4","signed_url":"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?X-Tos-Algorithm=...","url":"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?X-Tos-Algorithm=..."},"request_id":"req_abc123"},"schema":{"properties":{"data":{"properties":{"os_bucket":{"description":"存储桶名称。调用发布接口时传入 bucket_name 字段","example":"data-datanebula-object","type":"string"},"os_key":{"description":"对象存储路径。调用发布接口时传入 bucket_key 字段","example":"upload/abc123.mp4","type":"string"},"signed_url":{"description":"上传完成后的文件访问 URL（GET 方法，24小时有效）","example":"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?X-Tos-Algorithm=...","type":"string"},"url":{"description":"预签名上传 URL。使用 HTTP PUT 方法上传文件到此 URL，有效期 180 秒，走 TOS 加速端点","example":"https://data-datanebula-object.tos-accelerate.volces.com/upload/abc123.mp4?X-Tos-Algorithm=...","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":"RESOURCE_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":{"time_unit":"microsecond"},"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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":{"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":{"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":"RESOURCE_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":{"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":"RESOURCE_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":{"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":{"description":"原视频声音设置","properties":{"mode":{"description":"原视频声音策略：preserve=保留，mute=静音","enum":["preserve","mute"],"type":"string"},"volume":{"description":"原视频音量倍率，范围 0–2","maximum":2,"minimum":0,"type":"number"}},"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":{"description":"旁白生成设置及状态","properties":{"instructions":{"description":"语音生成说明，无值时为 null","nullable":true,"type":"string"},"language_code":{"description":"旁白语言代码","type":"string"},"rendered_at":{"description":"语音生成时间，RFC3339","format":"date-time","type":"string"},"source_type":{"description":"音色来源类型","type":"string"},"speaking_rate":{"description":"语速倍率","type":"number"},"status":{"description":"旁白素材状态","type":"string"},"voice_id":{"description":"音色 ID，无值时为 null","nullable":true,"type":"string"},"voice_profile_id":{"description":"自定义音色档案 ID，无值时为 null","nullable":true,"type":"string"}},"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":"RESOURCE_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":{"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":"RESOURCE_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":{"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":"RESOURCE_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":{"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":"RESOURCE_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":"RESOURCE_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":"RESOURCE_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":"创作者账号类型：0=个人账号，3=店铺运营号，4=店铺绑定号","example":0,"in":"query","name":"account_type","required":false,"schema":{"enum":[0,3,4],"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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":0.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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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":999.9,"credits_cost":1.2}},"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":"RESOURCE_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"},{"name":"广告营销/4.诊断与复盘"},{"name":"广告营销/5.投放准备"},{"name":"广告营销/6.受控创建"},{"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. 成功的任务结果会持久化，可以随时再次查询","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授权链接」）；Facebook、Instagram 与 TikTok Shop 挂车账号也支持各自的授权链接绑定。授权链接适合云手机、代运营或账号持有人不在身边的场景。\n\nTikTok、Facebook、Instagram 授权链接都会返回 `ref`。可将其原样传给「查询社媒授权绑定状态」（历史兼容路径 `POST /open/v1/social/tiktok/bind-status`）并轮询至 `status=bound`。Facebook 一次授权可能绑定多个 Page，绑定状态只返回首个成功绑定的 Page；完整结果以「社媒账号列表」为准。\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「文件上传」分类下提供普通版和加速版两个接口。两者都先获取临时上传地址，再使用 HTTP PUT 上传文件，但请求路径、返回字段和有效期不同。\n\n### 方式 A：调用「生成上传预签名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使用返回的 `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 请记录 `object_key` 和 `s3_bucket`。`presigned_url` 默认有效期 1 小时。\n\n### 方式 B：调用「（加速版）生成上传预签名URL」\n\n需要加速上传时，调用加速版接口：\n\n```bash\ncurl -X POST \"https://openapi.gateway.chuhaijiang.com/open/v1/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    \"url\": \"https://data-datanebula-object.tos-accelerate.volces.com/upload/xxx.mp4?...\",\n    \"os_key\": \"upload/xxx.mp4\",\n    \"os_bucket\": \"data-datanebula-object\",\n    \"signed_url\": \"https://data-datanebula-object.tos-accelerate.volces.com/upload/xxx.mp4?...\"\n  }\n}\n```\n\n使用返回的 `url` 上传文件：\n\n```bash\ncurl -X PUT \"{url}\" \\\n  -H \"Content-Type: video/mp4\" \\\n  --data-binary @my_video.mp4\n```\n\n\u003e 请记录 `os_key` 和 `os_bucket`。`url` 有效期 180 秒，获取后请立即上传；`signed_url` 是上传完成后的临时访问地址，有效期 24 小时。\n\n\u003e 无论选择哪种方式，都必须保留 `--data-binary @my_video.mp4` 中的 `@`，并将整个上传 URL 放在引号中。上传接口返回 HTTP 2xx 后，再进入下一步。文件大小限制取决于目标平台（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 普通版：`bucket_name = s3_bucket`、`object_key = object_key`；加速版：`bucket_name = os_bucket`、`object_key = os_key`。\n\u003e 注意：本接口的文件路径参数名为 `object_key`，与 Step 3 发布接口的 `bucket_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 = s3_bucket`、`bucket_key = object_key`；加速版：`bucket_name = os_bucket`、`bucket_key = os_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","广告营销/4.诊断与复盘","广告营销/5.投放准备","广告营销/6.受控创建"]},{"name":"小匠Agent","tags":["小匠Agent/1.对话","小匠Agent/2.会话与报告"]},{"name":"通用","tags":["异步任务","文件上传","账户"]}]}