# 视频数据同步

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[视频数据同步](/openapi/material-fetch)
- 完整接口约束：[JSON Schema](/openapi/operations/fetchPublicVideoData.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/material/fetch

接口标识：`fetchPublicVideoData`

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

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

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

请求格式：`application/json`

### 请求示例

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

### 成功响应

```json
{
  "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"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | 规范化字段与平台特有的公开内容字段。 |
| `data.videoId` | string | 否 | — |
| `data.uniqueId` | string | 否 | — |
| `data.playCount` | integer | 否 | — |
| `data.diggCount` | integer | 否 | — |
| `data.commentCount` | integer | 否 | — |
| `data.shareCount` | integer | 否 | — |
| `data.collectCount` | integer | 否 | — |
| `data.coverUrl` | string | 否 | — |
| `data.videoDesc` | string | 否 | — |
| `data.releaseAt` | integer | 否 | — |

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 404 | 公开作品不存在或已删除。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。