出海匠开放平台 API

出海匠开放平台 API，提供数据查询、内容制作、社媒管理、广告营销等能力。

认证

所有请求需在 Header 中携带 X-API-Key 或 Authorization: Bearer <API-Key>。

通用错误码

HTTP	Code	说明
400	BAD_REQUEST	请求格式错误
400	INVALID_PARAM	参数无效
400	MISSING_PARAM	缺少必填参数
400	INVALID_SORT_FIELD	排序字段不合法
400	INVALID_INCLUDE	include 参数不合法
400	PAGE_SIZE_EXCEEDED	分页大小超限
401	AUTH_MISSING_KEY	缺少 API Key
401	AUTH_INVALID_KEY	API Key 无效
401	AUTH_KEY_REVOKED	API Key 已吊销
401	AUTH_KEY_SUSPENDED	API Key 已暂停
402	INSUFFICIENT_CREDITS	credits 余额不足
403	FORBIDDEN_SCOPE	无权限访问此接口
404	ROUTE_NOT_FOUND	接口不存在
404	TASK_NOT_FOUND	异步任务不存在
429	RATE_LIMITED	请求频率超限
429	QUOTA_EXCEEDED	配额超限
500	INTERNAL_ERROR	内部错误
502	BACKEND_ERROR	后端服务错误
503	BACKEND_UNAVAILABLE	后端服务不可用
504	BACKEND_TIMEOUT	后端服务超时

商品分类 ID 参考

搜索接口的 category 参数需要传分类 ID（数字）。以下为 TikTok 一级分类列表：

分类 ID	分类名称
601450	美妆个护
601152	女士服装
700645	保健
603014	运动与户外
601739	手机与数码
600942	家电
824328	男士服装
605248	时尚配件
700437	食品饮料
600001	居家日用
604453	家具
600024	厨房用品
600154	家纺布艺
824584	箱包
604206	玩具和爱好
601352	鞋靴
604579	五金工具
604968	家装建材
602118	宠物用品
601755	电脑办公
602284	母婴用品
605196	汽车与摩托车
951432	收藏品
801928	图书/杂志/影音
953224	珠宝与衍生品
856720	二手商品
802184	儿童时尚

以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有商品。

数据查询/2.达人数据

参数说明

category：达人分类 ID（达人内容领域标签，与商品分类是两套不同体系），可选值见下方「达人分类 ID 参考」。也可不传此参数搜索，从返回结果的 category_label 字段获取分类 ID 后再用于精确筛选。
has_contact：是否有联系方式（true/false），筛选有公开邮箱/社交账号的达人

达人分类 ID 参考

分类 ID	分类名称
creator_category_v20240616_8	购物与零售
creator_category_v20240616_15	媒体与娱乐
creator_category_v20240616_10	美妆与时尚
creator_category_v20240616_14	个人博主
creator_category_v20240616_12	服装与配饰
creator_category_v20240616_32	公众人物
creator_category_v20240616_23	艺术与手工
creator_category_v20240616_17	运动与健身
creator_category_v20240616_24	健康与养生
creator_category_v20240616_13	音乐与舞蹈
creator_category_v20240616_9	家居、家具与家电
creator_category_v20240616_19	宠物与动物
creator_category_v20240616_18	教育
creator_category_v20240616_11	美食与饮品
creator_category_v20240616_31	汽车与交通
creator_category_v20240616_5	电子产品
creator_category_v20240616_29	游戏
creator_category_v20240616_30	专业服务
creator_category_v20240616_16	母婴
creator_category_v20240616_33	美食与烹饪
creator_category_v20240616_20	旅游与出行
creator_category_v20240616_27	金融与投资
creator_category_v20240616_2	机械与设备
creator_category_v20240616_21	品牌
creator_category_v20240616_25	咨询与服务
creator_category_v20240616_4	房产
creator_category_v20240616_28	政府与政治
creator_category_v20240616_6	餐厅与酒吧
creator_category_v20240616_26	IT 与高科技
creator_category_v20240616_22	软件与应用
creator_category_v20240616_3	直播公会
creator_category_v20240616_7	影视与制片
creator_category_v20240616_34	其他

达人分类与主播（直播）分类共用同一套体系，上表同样适用于「直播数据」的 category 参数。

数据查询/3.视频数据

参数说明

is_commercial：是否为带货视频（true/false）

商品分类 ID 参考

category 参数为视频关联的商品分类 ID：

分类 ID	分类名称
601450	美妆个护
601152	女士服装
700645	保健
603014	运动与户外
601739	手机与数码
600942	家电
824328	男士服装
605248	时尚配件
700437	食品饮料
600001	居家日用
604453	家具
600024	厨房用品
600154	家纺布艺
824584	箱包
604206	玩具和爱好
601352	鞋靴
604579	五金工具
604968	家装建材
602118	宠物用品
601755	电脑办公
602284	母婴用品
605196	汽车与摩托车
951432	收藏品
801928	图书/杂志/影音
953224	珠宝与衍生品
856720	二手商品
802184	儿童时尚

以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有视频。

数据查询/4.店铺数据

参数说明

seller_type：卖家类型（1=海外非品牌, 2=本地, 3=品牌, 4=非品牌）

商品分类 ID 参考

category 参数为店铺主营商品分类 ID，与商品搜索使用同一套分类体系：

分类 ID	分类名称
601450	美妆个护
601152	女士服装
700645	保健
603014	运动与户外
601739	手机与数码
600942	家电
824328	男士服装
605248	时尚配件
700437	食品饮料
600001	居家日用
604453	家具
600024	厨房用品
600154	家纺布艺
824584	箱包
604206	玩具和爱好
601352	鞋靴
604579	五金工具
604968	家装建材
602118	宠物用品
601755	电脑办公
602284	母婴用品
605196	汽车与摩托车
951432	收藏品
801928	图书/杂志/影音
953224	珠宝与衍生品
856720	二手商品
802184	儿童时尚

以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有店铺。

数据查询/5.广告与创意情报

数据查询/6.直播数据

参数说明

category：主播分类 ID，与达人分类使用同一套体系，可选值见下方「主播分类 ID 参考」。也可不传此参数搜索。
is_living：是否正在直播（true/false）
is_commercial：是否为带货直播（true/false）

主播分类 ID 参考

分类 ID	分类名称
creator_category_v20240616_8	购物与零售
creator_category_v20240616_15	媒体与娱乐
creator_category_v20240616_10	美妆与时尚
creator_category_v20240616_14	个人博主
creator_category_v20240616_12	服装与配饰
creator_category_v20240616_32	公众人物
creator_category_v20240616_23	艺术与手工
creator_category_v20240616_17	运动与健身
creator_category_v20240616_24	健康与养生
creator_category_v20240616_13	音乐与舞蹈
creator_category_v20240616_9	家居、家具与家电
creator_category_v20240616_19	宠物与动物
creator_category_v20240616_18	教育
creator_category_v20240616_11	美食与饮品
creator_category_v20240616_31	汽车与交通
creator_category_v20240616_5	电子产品
creator_category_v20240616_29	游戏
creator_category_v20240616_30	专业服务
creator_category_v20240616_16	母婴
creator_category_v20240616_33	美食与烹饪
creator_category_v20240616_20	旅游与出行
creator_category_v20240616_27	金融与投资
creator_category_v20240616_2	机械与设备
creator_category_v20240616_21	品牌
creator_category_v20240616_25	咨询与服务
creator_category_v20240616_4	房产
creator_category_v20240616_28	政府与政治
creator_category_v20240616_6	餐厅与酒吧
creator_category_v20240616_26	IT 与高科技
creator_category_v20240616_22	软件与应用
creator_category_v20240616_3	直播公会
creator_category_v20240616_7	影视与制片
creator_category_v20240616_34	其他

category（主播分类）与下方 product_category（带货商品分类）是两套不同体系，不要混用。

商品分类 ID 参考

product_category 参数为直播带货的商品分类 ID：

分类 ID	分类名称
601450	美妆个护
601152	女士服装
700645	保健
603014	运动与户外
601739	手机与数码
600942	家电
824328	男士服装
605248	时尚配件
700437	食品饮料
600001	居家日用
604453	家具
600024	厨房用品
600154	家纺布艺
824584	箱包
604206	玩具和爱好
601352	鞋靴
604579	五金工具
604968	家装建材
602118	宠物用品
601755	电脑办公
602284	母婴用品
605196	汽车与摩托车
951432	收藏品
801928	图书/杂志/影音
953224	珠宝与衍生品
856720	二手商品
802184	儿童时尚

以上为一级分类，搜索时传一级分类 ID 可筛选该大类下所有直播。

数据查询/7.亚马逊数据

内容制作/1.AI 视频

接口中所有 *_url 字段需要公网可访问的地址；如需上传本地文件，请先通过「文件上传」分类下的「生成上传预签名URL」接口获取。

内容制作/2.AI 图片

接口中所有 *_url 字段需要公网可访问的地址；如需上传本地文件，请先通过「文件上传」分类下的「生成上传预签名URL」接口获取。

通过「上传并发布视频」接口一步完成发布，支持立即发布和定时发布，支持多账号同时发布。

前置条件：绑定社媒账号

发布前必须先绑定至少一个社媒账号。前往「社媒管理/1.账号管理」分类，调用「TikTok扫码登录」+「TikTok扫码状态查询」通过扫码绑定。绑定完成后，通过「社媒账号列表」获取 id 字段，即为下方发布接口所需的 platform_account_id。

Step 1: 上传文件

1.1 调用「生成上传预签名URL」获取临时上传地址（该接口在「文件上传」分类下）

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/upload/presigned-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "my_video.mp4"}'

返回示例：


Code
{
  "data": {
    "presigned_url": "https://data-datanebula-object.tos-ap-southeast-1.volces.com/upload/my_video.mp4_xxx?...",
    "object_key": "upload/my_video.mp4_xxx",
    "s3_bucket": "data-datanebula-object",
    "cdn_url": "https://oss-data.chuhaijiang.com/upload%2Fmy_video.mp4_xxx?..."
  }
}

请记录返回的 object_key 和 s3_bucket，后续步骤需要用到。

1.2 使用 PUT 请求上传文件到 presigned_url

Code
curl -X PUT "{presigned_url}" \
  -H "Content-Type: video/mp4" \
  --data-binary @my_video.mp4

presigned_url 有效期 1 小时，文件大小限制取决于目标平台（TikTok 最大 4GB，YouTube 最大 256GB，Instagram Reels 最大 1GB）。

Step 2: 视频信息校验（推荐）

上传完成后，建议调用「视频信息校验」检查视频是否符合目标平台的规格要求（分辨率、时长、比特率等），避免发布失败：

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/videos/check-info" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket_name": "data-datanebula-object", "object_key": "upload/my_video.mp4_xxx"}'

该接口会检查视频的编码格式、分辨率、时长等是否满足 TikTok、YouTube、Instagram 等平台的要求。注意：本接口的文件路径参数名为 object_key，与 Step 3 发布接口的 bucket_key 不同，两者的值相同（均为 Step 1 返回的 object_key）。

Step 3: 调用「上传并发布视频」

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/publish/upload-and-publish" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_title": "My Video",
    "video_description": "Check this out!",
    "bucket_name": "data-datanebula-object",
    "bucket_key": "upload/my_video.mp4_xxx",
    "publications": [
      {
        "platform_account_id": 4687,
        "title": "Check out this video!",
        "platform_config": "{\"privacy\":\"PUBLIC_TO_EVERYONE\"}"
      }
    ]
  }'

bucket_name = Step 1 返回的 s3_bucket，bucket_key = Step 1 返回的 object_key。支持同时发布到多个账号（publications 数组）。返回的 session_token 用于查询发布进度。

定时发布

在 publications 中设置 scheduled_at（Unix 秒级时间戳），即可定时发布。不同账号可设置不同的发布时间：


Code
{
  "video_title": "My Video",
  "bucket_name": "data-datanebula-object",
  "bucket_key": "upload/my_video.mp4_xxx",
  "publications": [
    {
      "platform_account_id": 4687,
      "title": "Publish now",
      "platform_config": "{\"privacy\":\"PUBLIC_TO_EVERYONE\"}"
    },
    {
      "platform_account_id": 5678,
      "title": "Publish tomorrow",
      "scheduled_at": 1774100400,
      "platform_config": "{\"share_to_feed\":true}"
    }
  ]
}

scheduled_at 需在 5 分钟 ~ 90 天内。不传或为 0 表示立即发布；小于 5 分钟自动降级为立即发布。已定时的发布可通过「改期」接口修改时间。

Step 4: 调用「发布会话状态」轮询进度

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/publish/session" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_token": "127169e7-35e3-40..."}'

建议轮询间隔 3~5 秒，重复调用直到状态为完成或失败。

取消发布（可选）

调用「取消发布会话」取消上传中的会话：POST /open/v1/social/publish/session/cancel
调用「取消单个发布」取消已提交的发布：POST /open/v1/social/publish/cancel

通过私信接口收发 WhatsApp / WhatsApp Business / LINE / TikTok / Facebook / Instagram 的私信消息，支持文本与图片/视频/文档等媒体消息、引用回复。

核心概念

渠道（channel）：绑定到私信系统的一个社媒账号（一个 WhatsApp 号码、一个 TikTok 账号即一个渠道），渠道下包含与多个联系人的会话
会话（conversation）：渠道与单个联系人（或群）的对话线程
发送窗口：部分平台限制商家主动发消息的时间窗——WhatsApp Business / Facebook / Instagram 为客户最后一条消息后 24 小时，TikTok 为 48 小时且最多 10 条，WhatsApp 个人版 / LINE 无限制。窗口外发送会失败

Step 1: 获取渠道列表

调用「私信渠道列表」查看已绑定的社媒账号，记录 channel_id：

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/im/channels/list" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "offset": 0}'

limit 和 offset 必填。默认只返回 active 状态的渠道。

Step 2: 获取会话列表

用 channel_id 调用「私信会话列表」，拿到 conversation_id 和发送窗口状态：

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/im/conversations/list" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": "550e8400-e29b-41d4-a716-446655440000", "limit": 20}'

列表固定排序：置顶会话在前，其余按最后消息时间倒序。发消息前先检查会话的 window_info.can_send_message。

Step 3: 拉取消息

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/im/conversations/12345/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20}'

传 mark_as_read: true 会将会话标记为已读并向平台发送已读回执（如 WhatsApp 蓝勾），对方可感知，请按需使用。

Step 4: 发送消息

文本消息直接发送：

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/im/messages/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "12345", "message_type": "text", "content": "您好，您咨询的商品有货。"}'

发送图片/视频/文档需先上传文件（三步）：

调用「私信上传预签名 URL」获取上传地址（私信专用存储，与「文件上传」分类下的通用上传接口不通用）
对返回的 presigned_url 发起 HTTP PUT 上传文件本体（Content-Type 与申请时一致）
发送消息时在 media 中带上返回的 object_key 和 s3_bucket：

Code
curl -X POST "https://openapi.gateway.chuhaijiang.com/open/v1/social/im/messages/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "12345",
    "message_type": "image",
    "media": {
      "s3_key": "im/2026/07/10/20260710153000_photo.jpg",
      "s3_bucket": "datanebula-object",
      "filename": "photo.jpg",
      "mime_type": "image/jpeg"
    }
  }'

发送为同步执行，成功返回 status: sent。发送窗口关闭时返回业务错误码 20510；10 秒内向同一会话重复发送相同内容会命中幂等去重。

获取新消息

暂不提供消息推送，请通过轮询获取增量消息：先调「私信未读数汇总」检查各渠道未读数，有未读时用「私信会话列表」（filter_unread: true）定位会话，再拉取消息列表。

异步任务使用流程

提交任务（如 POST /open/v1/ai/videos/content-analysis）→ 返回 task_id
轮询状态：GET /open/v1/tasks/{task_id}
- status="running" → 继续轮询（建议间隔 3-5 秒）
- status="success" → result 字段包含完整结果
- status="failed" → error_message 字段包含错误信息
成功的任务结果会持久化，可以随时再次查询

以下接口为异步任务：所有 AI 分析、AI 生成类接口。提交后立即返回 task_id，不会阻塞等待。

文件上传

账户

查询账户状态、tier 等级与 credits 余额。

Schemas

APIError APIResponse UsageInfo

Contact出海匠info@chuhaijiang.com

Servers

https://openapi.gateway.chuhaijiang.com

生产环境

出海匠开放平台 API

认证

通用错误码

商品分类 ID 参考

参数说明

达人分类 ID 参考

参数说明

商品分类 ID 参考

参数说明

商品分类 ID 参考

参数说明

主播分类 ID 参考

商品分类 ID 参考

前置条件：绑定社媒账号

Step 1: 上传文件

1.1 调用「生成上传预签名URL」获取临时上传地址（该接口在「文件上传」分类下）

1.2 使用 PUT 请求上传文件到 presigned_url

Step 2: 视频信息校验（推荐）

Step 3: 调用「上传并发布视频」

定时发布

Step 4: 调用「发布会话状态」轮询进度

取消发布（可选）

核心概念

Step 1: 获取渠道列表

Step 2: 获取会话列表

Step 3: 拉取消息

Step 4: 发送消息

获取新消息

更多能力

异步任务使用流程

出海匠开放平台 API

认证

通用错误码

商品分类 ID 参考

参数说明

达人分类 ID 参考

参数说明

商品分类 ID 参考

参数说明

商品分类 ID 参考

参数说明

主播分类 ID 参考

商品分类 ID 参考

前置条件：绑定社媒账号

Step 1: 上传文件

1.1 调用「生成上传预签名URL」获取临时上传地址（该接口在「文件上传」分类下）

1.2 使用 PUT 请求上传文件到 presigned_url

Step 2: 视频信息校验（推荐）

Step 3: 调用「上传并发布视频」

定时发布

Step 4: 调用「发布会话状态」轮询进度

取消发布（可选）

核心概念

Step 1: 获取渠道列表

Step 2: 获取会话列表

Step 3: 拉取消息

Step 4: 发送消息

获取新消息

更多能力

异步任务使用流程