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 接口索引 JSON AI 生成工作流 MD

Commerce publishing

带货内容发布

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

GET/v1/creatorAccount/pageList已上线

operationId: listCreatorAccounts

AI Markdown OpenAPI JSON

查询已授权达人

查询 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/listByShowcase已上线

operationId: listTikTokShowcaseProducts

AI Markdown OpenAPI JSON

查询橱窗商品

查询达人橱窗商品。创建发布任务时，商品来源 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"
}

POST/v1/creator/tiktokshop/product/addToShowcase已上线

operationId: addTikTokShowcaseProducts

AI Markdown OpenAPI JSON

创作者TTS-添加橱窗商品

将 TikTok Shop 商品添加到创作者展示橱窗。可按商品 ID 批量添加，或通过单个商品链接添加。

请求字段

字段	类型	必填	说明
`id`	`integer`	是	创作者账号 ID（creator account id）
`addType`	`PRODUCT_ID \| PRODUCT_LINK`	是	添加方式
`productIds`	`string[]`	条件	addType=PRODUCT_ID 时必填，1～20 个商品 ID
`productLink`	`string(uri)`	条件	addType=PRODUCT_LINK 时必填

所需 scope：creator.showcase.write、creator.video.write。

一次最多添加 20 个 productId。

业务 code=0 时仍需检查 data.errors；存在 errors 表示对应商品添加失败。

创作者授权失效时返回业务错误「授权过期，请重新授权」。

请求体

{
  "id": 12345,
  "addType": "PRODUCT_ID",
  "productIds": [
    "1732280564607717841",
    "1732280564607717842"
  ]
}

成功响应

{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 16001001,
        "message": "Product is unavailable for this creator",
        "detail": {
          "productId": "1732280564607717842"
        }
      }
    ]
  },
  "message": "success",
  "timestamp": 1786406400000
}

File upload

文件上传

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

POST/v1/file/presign已上线

operationId: createFileUpload

AI Markdown OpenAPI JSON

获取预签名上传地址

提交文件信息和兼容 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

AI Markdown OpenAPI JSON

确认文件上传完成

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

请求字段

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

请求体

{
  "fileId": 591
}

成功响应

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

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

operationId: createCreatorPost

AI Markdown OpenAPI JSON

创建发布任务

创建 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 时区
`oauthRegion`	`string`	否	达人 OAuth 授权地区
`coverFileId`	`integer \| string`	否	自定义视频封面文件 ID；与 tiktokShop.coverUri 配套传递，图文不传
`tiktokShop`	`object`	条件	VIDEO 时必填，包含商品、封面、预审、音乐和 AI 标识
`tiktokShop.preCheck`	`boolean`	否	是否在发布前提交预审，默认 false
`tiktokShop.isAiGenerated`	`boolean`	否	是否标识为 AI 生成内容；为 true 时 TikTok 会添加“AI 生成”标签
`tiktokShop.coverUri`	`string`	否	封面上传接口返回的 URI；使用时同时传 coverFileId
`tiktokShop.coverTimestampMs`	`integer`	否	从视频指定毫秒位置截帧作为封面；有 coverUri 时不传
`tiktokShop.musicInfo`	`object`	否	视频背景音乐；不需要音乐时不传
`tiktokShop.musicInfo.id`	`string`	条件	传 musicInfo 时必填的音乐 ID
`tiktokShop.productInfo.productId`	`string`	条件	VIDEO 时必填；商品接口返回的商品 ID
`tiktokShop.productInfo.title`	`string`	条件	VIDEO 时必填；购物车展示标题，最长 30 字符
`tiktokShop.productInfo.source`	`SHOP \| SHOWCASE`	条件	VIDEO 时必填；店铺商品传 SHOP，橱窗商品传 SHOWCASE
`tiktokShopPhoto`	`object`	条件	PHOTO 时必填
`tiktokShopPhoto.postType`	`MULTI_PHOTO_ONE_ANCHOR`	条件	PHOTO 时固定传 MULTI_PHOTO_ONE_ANCHOR
`tiktokShopPhoto.businessIds`	`string[]`	条件	PHOTO 时必填；1～15 个图片 fileId，按最终展示顺序排列
`tiktokShopPhoto.productLinks[0].productId`	`string`	条件	PHOTO 时必填；唯一挂车商品的商品 ID
`tiktokShopPhoto.productLinks[0].title`	`string`	条件	PHOTO 时必填；购物车展示标题，最长 30 字符
`tiktokShopPhoto.productLinks[0].source`	`SHOP \| SHOWCASE`	条件	PHOTO 时必填；商品来源
`tiktokShopPhoto.musicInfo`	`object`	否	图文背景音乐；不需要音乐时不传
`tiktokShopPhoto.musicInfo.id`	`string`	条件	传 musicInfo 时必填的音乐 ID

视频封面可传 tiktokShop.coverTimestampMs 截帧；自定义封面则同时传 coverFileId 与 tiktokShop.coverUri，两种方式不要混用。

图文支持 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": {
    "preCheck": false,
    "isAiGenerated": true,
    "coverTimestampMs": 1500,
    "musicInfo": {
      "id": "7567668059796720391",
      "title": "original sound",
      "author": "Ivan",
      "duration": "15"
    },
    "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"
      }
    ],
    "musicInfo": {
      "id": "7567668059796720391",
      "title": "original sound",
      "author": "Ivan",
      "duration": "15"
    }
  }
}

AI content generation

AI 内容生成

创建图片或视频生成计划，并使用同一个 scheduleId 查询，直到生成结果可用。

POST/v1/ai/schedule/create已上线

operationId: createAiGenerationSchedule

AI Markdown OpenAPI JSON

创建 AI 图片或视频生成任务

创建 AI 图片或视频生成计划，支持提示词、参考图、模型、尺寸和批量数量。使用响应中的 scheduleId 查询任务状态与生成结果。

请求字段

字段	类型	必填	说明
`taskId`	`string`	否	调用方生成的任务标识；建议使用 8 位小写字母或数字
`type`	`IMAGE_GENERATION \| VIDEO_GENERATION`	是	生成内容类型
`params.prompt`	`string`	是	图片或视频生成提示词
`params.model`	`gpt-image-2 \| nano-banana-2 \| nano-banana-2-2k \| nano-banana-2-4k \| seedream5.0-lite \| gemini-omni-video \| veo3.1-lite-extend \| veo3.1-extend \| grok-imagine-1.5 \| seedance2.0-mini \| seedance2.0 \| seedance2.0-fast`	是	根据 type 选择下方列出的图片或视频模型
`params.aspectRatio`	`string`	条件	图片生成时使用，例如 1:1、9:16
`params.seconds`	`integer`	条件	视频生成时长；可选值取决于模型
`params.size`	`string`	条件	视频尺寸，例如 720x1280
`params.inputReference`	`string(uri)`	否	单张远程参考图 URL，主要用于视频生成
`params.inputReferences`	`string(uri)[]`	否	按顺序传入的远程参考图 URL；不支持 data URL
`params.watermark`	`boolean`	否	视频是否添加水印，默认 false
`nums`	`integer`	是	生成数量，未指定多结果时建议传 1
`businessId`	`string`	否	需要关联的业务对象 ID
`businessType`	`MERCHANT_SKU \| AI_PURCHASE_TASK`	否	业务对象类型
`promptId`	`string`	否	已保存的提示词 ID
`execAt`	`string(date-time)`	否	ISO 8601 执行时间；省略时立即创建
`name`	`string`	否	生成计划显示名称

图片模型：gpt-image-2、nano-banana-2、nano-banana-2-2k、nano-banana-2-4k、seedream5.0-lite。

视频模型：gemini-omni-video、veo3.1-lite-extend、veo3.1-extend、grok-imagine-1.5、seedance2.0-mini、seedance2.0、seedance2.0-fast。

视频时长：gemini-omni-video 支持 6/8/10 秒；veo3.1-lite-extend 和 veo3.1-extend 固定 8 秒；grok-imagine-1.5 支持 6/10/15/20/25/30 秒；seedance2.0-mini、seedance2.0 和 seedance2.0-fast 支持 4/8/10/12/15 秒。

图片生成传 IMAGE_GENERATION 与 params.aspectRatio；视频生成传 VIDEO_GENERATION、params.seconds 和 params.size。

参考图必须是可访问的 http/https URL；本地文件需先上传后再传入 URL。

scheduleId 与 taskId 不同。创建成功后请使用 scheduleId 查询本计划的任务列表，不要因轮询中断而重复创建。

成功响应

{
  "code": 0,
  "data": {
    "scheduleId": "schedule_01k1example",
    "taskIds": [
      "task_01k1example"
    ]
  },
  "message": "success"
}

图片生成

{
  "taskId": "img8a1b2",
  "type": "IMAGE_GENERATION",
  "params": {
    "prompt": "A clean product hero image on a bright studio background",
    "model": "gpt-image-2",
    "aspectRatio": "1:1",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ]
  },
  "nums": 1,
  "name": "Product hero image"
}

视频生成

{
  "taskId": "vid8c3d4",
  "type": "VIDEO_GENERATION",
  "params": {
    "prompt": "A clean 10-second product reveal video with a slow camera push-in",
    "model": "gemini-omni-video",
    "seconds": 10,
    "size": "720x1280",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ],
    "watermark": false
  },
  "nums": 1,
  "name": "Product reveal video"
}

GET/v1/ai/task/listByScheduleId已上线

operationId: listAiTasksByScheduleId

AI Markdown OpenAPI JSON

查询 AI 生成任务结果

使用创建接口返回的 scheduleId 查询本次图片或视频生成任务。建议每 5 秒轮询，直到任务完成或明确失败。

Query 参数

字段	类型	必填	说明
`scheduleId`	`string`	是	创建生成计划时返回的 scheduleId

等待状态包括 WAITING_SUBMIT、SUBMITTING、PENDING 和 PROCESSING；成功状态为 COMPLETED。

失败、取消或过期后再决定是否重试；网络错误或轮询进程退出不表示生成任务失败。

视频优先读取 customResult.videoUrl 或 result.url；图片通常读取 result.url 或 resultUrl。

成功响应

{
  "code": 0,
  "data": {
    "list": [
      {
        "taskId": "task_01k1example",
        "scheduleId": "schedule_01k1example",
        "type": "VIDEO_GENERATION",
        "status": "COMPLETED",
        "model": "gemini-omni-video",
        "params": {
          "prompt": "A clean 10-second product reveal video with a slow camera push-in",
          "model": "gemini-omni-video",
          "seconds": 10,
          "size": "720x1280"
        },
        "result": {
          "url": "https://static.ailingtu.com/ai-videos/result.mp4",
          "thumbnailUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "customResult": {
          "videoUrl": "https://static.ailingtu.com/ai-videos/result.mp4",
          "coverUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "createdAt": "2026-08-10T10:00:00Z"
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1
  },
  "message": "success"
}

Content data

内容数据

POST/v1/material/fetch已上线

operationId: fetchPublicVideoData

AI Markdown OpenAPI JSON

视频数据同步

根据公开作品链接同步 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 参数

创作者TTS-添加橱窗商品

请求字段

文件上传

获取预签名上传地址

请求字段

确认文件上传完成

请求字段

创建发布任务

请求字段

AI 内容生成

创建 AI 图片或视频生成任务

请求字段

查询 AI 生成任务结果

Query 参数

内容数据

视频数据同步

请求字段

联调检查清单

准备开始接入？