OpenAPI 接口文档

发布流程

https://api.ailingtu.com

查询达人

id + creatorId

选择商品

SHOP / SHOWCASE

上传素材

presign → PUT → confirm

创建发布任务

VIDEO / PHOTO

鉴权方式

x-api-key: <YOUR_API_KEY>

API Key 仅保存在服务端，不要暴露在浏览器代码、排期表或日志中。

成功判断

HTTP 2xx && response.code === 0

HTTP 非 2xx、响应不是合法 JSON 或业务 code 非 0，均应按失败处理。

机器可读接口规范

AI Agent、SDK 生成和契约校验应优先读取 OpenAPI 规范。

OpenAPI JSON JSON OpenAPI YAML YAML Markdown 文档 MD llms.txt TXT

Commerce publishing

带货内容发布

创建 TikTok Shop 发布任务前，先查询并确认达人账号与商品。

GET/v1/creatorAccount/pageList已上线

operationId: listCreatorAccounts

查询已授权达人

查询 TikTok Shop 已授权达人、目标地区和发布权限。响应中的 id 用于查商品，creatorId 用于创建发布任务。

Query 参数

字段	类型	必填	说明
`pageSize`	`integer`	是	每页数量，最大 200
`pageNumber`	`integer`	是	页码，从 1 开始
`valid`	`boolean`	否	是否只返回有效授权，默认 true
`authSource`	`string`	否	带货发布传 TIKTOK_SHOP_CREATOR
`usernames`	`string[]`	否	重复 Query 参数传递多个用户名
`selectionRegion`	`string`	否	目标地区，例如 US
`hasPhotoPermission`	`boolean`	否	仅返回有带货图文权限的账号

带货图文需确认 permissions 包含 PHOTO_SHOPPABLE_PERMISSION_PRODUCT。

成功响应

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 12345,
        "creatorId": "2077242233106595840",
        "username": "shop_creator",
        "authSource": "TIKTOK_SHOP_CREATOR",
        "oauthRegion": "USA",
        "registerRegion": "US",
        "selectionRegion": "US",
        "targetMarket": "US",
        "valid": true,
        "tagNames": [
          "top-tier"
        ],
        "permissions": [
          "VIDEO_SHOPPABLE_PERMISSION",
          "PHOTO_SHOPPABLE_PERMISSION_PRODUCT"
        ]
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 200,
    "totalPages": 1
  },
  "message": "success"
}

GET/v1/creator/tiktokshop/product/listByShop已上线

operationId: listTikTokShopProducts

查询店铺商品

使用达人账号表 id 查询 TikTok Shop 店铺商品。创建发布任务时，商品来源 source 应传 SHOP。

Query 参数

字段	类型	必填	说明
`id`	`integer`	是	达人账号表 id，不是 creatorId
`origin`	`TIKTOK`	是	固定传 TIKTOK
`pageSize`	`integer`	是	每页数量
`pageToken`	`string`	否	上一页返回的分页 Token
`titleKeyword`	`string`	否	商品标题关键词

成功响应

{
  "code": 0,
  "data": {
    "products": [
      {
        "id": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "price": {
          "amount": "19.99",
          "currency": "USD"
        },
        "images": [
          {
            "url": "https://cdn.example.com/product.jpg",
            "width": 800,
            "height": 800
          }
        ]
      }
    ],
    "nextPageToken": "",
    "totalCount": 1
  },
  "message": "success"
}

GET/v1/creator/tiktokshop/product/listByShowcase已上线

operationId: listTikTokShowcaseProducts

查询橱窗商品

查询达人橱窗商品，响应结构与店铺商品一致。创建发布任务时，商品来源 source 应传 SHOWCASE。

Query 参数

字段	类型	必填	说明
`id`	`integer`	是	达人账号表 id
`origin`	`TIKTOK`	是	固定传 TIKTOK
`pageSize`	`integer`	是	每页数量
`pageToken`	`string`	否	上一页返回的分页 Token

该接口不接收 titleKeyword；如需搜索，请在客户端按 title 过滤。

成功响应

{
  "code": 0,
  "data": {
    "products": [
      {
        "id": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "price": {
          "amount": "19.99",
          "currency": "USD"
        },
        "images": [
          {
            "url": "https://cdn.example.com/product.jpg",
            "width": 800,
            "height": 800
          }
        ]
      }
    ],
    "nextPageToken": "",
    "totalCount": 1
  },
  "message": "success"
}

File upload

文件上传

申请预签名地址，将媒体文件直传对象存储，并确认新文件上传完成。

POST/v1/file/presign已上线

operationId: createFileUpload

获取预签名上传地址

提交文件信息和兼容 Hash，获取 fileId 与对象存储上传地址。isNew=false 表示文件已存在，可跳过上传和确认。

请求字段

字段	类型	必填	说明
`fileName`	`string`	是	包含扩展名的文件名
`contentType`	`string`	是	文件 MIME 类型
`size`	`integer`	是	文件字节数
`hash`	`string`	是	文件字节转小写 hex 后，再计算 SHA-256

isNew=true 时，使用相同 Content-Type 将原始文件 PUT 到 uploadUrl，成功后再调用 confirm。

对象存储 PUT 请求不要携带 x-api-key。

请求体

{
  "fileName": "video.mp4",
  "contentType": "video/mp4",
  "size": 12345678,
  "hash": "3786a02b..."
}

成功响应

{
  "code": 0,
  "data": {
    "fileId": 591,
    "uploadUrl": "https://object-storage.example.com/presigned-url",
    "url": "https://cdn.ailingtu.com/media/video.mp4",
    "isNew": true,
    "expiresAt": "2026-07-29T12:00:00Z"
  },
  "message": "success"
}

POST/v1/file/confirm已上线

operationId: confirmFileUpload

确认文件上传完成

仅在新文件成功 PUT 到预签名地址后调用。秒传文件不需要确认。

请求字段

字段	类型	必填	说明
`fileId`	`integer \| string`	是	预签名接口返回的文件 ID

请求体

{
  "fileId": 591
}

成功响应

{
  "code": 0,
  "data": {
    "fileId": 591,
    "confirmed": true
  },
  "message": "success"
}

POST/v1/creator/post/create已上线

operationId: createCreatorPost

创建发布任务

创建 TikTok Shop 带货视频或带货图文发布任务。请求成功仅表示任务已接收，最终结果请在发布记录中确认。

请求字段

字段	类型	必填	说明
`businessId`	`string`	是	视频 fileId；图文为首图 fileId
`businessType`	`FILE`	是	上传文件固定传 FILE
`creatorId`	`string`	是	达人接口返回的 creatorId
`title`	`string`	是	发布文案，最长 4000 字符
`platform`	`TIKTOK_SHOP`	是	带货发布传 TIKTOK_SHOP
`mediaType`	`VIDEO \| PHOTO`	是	明确指定视频或图文
`scheduledAt`	`integer`	否	Unix Epoch 毫秒
`scheduledTz`	`string`	否	IANA 时区
`tiktokShop`	`object`	条件	VIDEO 时必填
`tiktokShopPhoto`	`object`	条件	PHOTO 时必填

图文支持 1～15 张图片和 1 个商品；businessId 必须等于 businessIds[0]。

保存 postId 和 status，并前往发布记录确认最终状态。

成功响应

{
  "code": 0,
  "data": {
    "id": 100,
    "postId": "post_xxx",
    "platform": "TIKTOK_SHOP",
    "title": "Summer Sale 2026 #summer",
    "videoUrl": "https://cdn.ailingtu.com/media/video.mp4",
    "status": "SCHEDULED"
  },
  "message": "success"
}

带货视频

{
  "businessId": "591",
  "businessType": "FILE",
  "creatorId": "2077242233106595840",
  "title": "Summer Sale 2026 #summer",
  "platform": "TIKTOK_SHOP",
  "mediaType": "VIDEO",
  "scheduledAt": 1784896665989,
  "scheduledTz": "America/New_York",
  "oauthRegion": "USA",
  "tiktokShop": {
    "productInfo": {
      "productId": "1732280564607717841",
      "title": "Summer Vibes Cord",
      "source": "SHOP"
    }
  }
}

带货图文

{
  "businessId": "591",
  "businessType": "FILE",
  "creatorId": "2077242233106595840",
  "title": "Summer Sale 2026 #summer",
  "platform": "TIKTOK_SHOP",
  "mediaType": "PHOTO",
  "scheduledAt": 1784896665989,
  "scheduledTz": "America/New_York",
  "oauthRegion": "USA",
  "tiktokShopPhoto": {
    "postType": "MULTI_PHOTO_ONE_ANCHOR",
    "businessIds": [
      "591",
      "592"
    ],
    "productLinks": [
      {
        "productId": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "source": "SHOP"
      }
    ]
  }
}

Content data

内容数据

POST/v1/material/fetch已上线

operationId: fetchPublicVideoData

视频数据同步

根据公开作品链接同步 TikTok、Instagram、抖音、小红书、视频号和 YouTube 的播放与互动数据。

请求字段

字段	类型	必填	说明
`videoUrl`	`string(uri)`	是	公开作品的 http/https 链接

请求体

{
  "videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678"
}

成功响应

{
  "code": 0,
  "data": {
    "videoId": "7624922739500993822",
    "uniqueId": "creator",
    "playCount": 2109422,
    "diggCount": 143027,
    "commentCount": 1320,
    "shareCount": 36150,
    "collectCount": 17710,
    "coverUrl": "https://cdn.example.com/cover.jpg",
    "videoDesc": "caption #tag",
    "releaseAt": 1775315687
  },
  "message": "success"
}

联调检查清单

区分商品查询 id 与发布 creatorId

isNew=false 时跳过 PUT 和 confirm

图文 businessIds 严格保持展示顺序

保存 postId 并确认最终发布状态

准备开始接入？

前往灵途 AI 工作台创建或管理 API Key。

管理 API Key

灵途 AI 开放 API

发布流程

机器可读接口规范

带货内容发布

查询已授权达人

Query 参数

查询店铺商品

Query 参数

查询橱窗商品

Query 参数

文件上传

获取预签名上传地址

请求字段

确认文件上传完成

请求字段

创建发布任务

请求字段

内容数据

视频数据同步

请求字段

联调检查清单

准备开始接入？