> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# TikTok 原声
> 按 clip ID 或 URL 采集公开 TikTok 音乐与原声元数据。
# TikTok 原声
按 clip ID 或原声 URL 采集公开 TikTok 音乐与原声元数据。
```json theme={"system"}
{
"music_id": "7439295283975702544"
}
```
## 通过 MCP 使用
| 接口 | 值 |
| ----------- | -------------------------------------------- |
| REST | `POST /v1/tiktok/song` |
| Compact MCP | `socq_execute`，并设置 `endpoint: "tiktok/song"` |
| 类型化 MCP | `socq_tiktok_song` |
| 精确工具 URL | `https://api.socq.ai/mcp?tools=tiktok_song` |
| CLI | `socq tiktok song` |
使用 `socq_execute` 时，将上面的 JSON 请求体作为 `input` 对象传入；也可以将相同字段直接传给类型化 MCP 工具。类型化 MCP 工具还支持 `_wait_seconds`、`_result_limit` 和 `_idempotency_key`。
提交成功后会返回 `task_id`。继续调用 `socq_get_task` 直到任务成功，然后从 `results.items` 读取标准化记录。
完整的提交和轮询流程请参阅 [MCP 快速开始](/zh/integrations/mcp)。
## 结果字段
任务结果使用下方稳定的 SocQ 字段。系统会统一来源特有的字段名和格式，但不会推断或补充来源未提供的数据。如需缩小返回字段集合，MCP 查询使用 `fields`，Typed 工具使用 `_result_fields`，CLI 使用 `--result-fields`。声明字段的值为 `null` 时仍会保留。
| 字段 | 类型 | 可空 | 说明 |
| ---------------------- | --------- | -- | ---------------------------------------- |
| `id` | `string` | 是 | 当前结果项的唯一标识。 |
| `platform` | `string` | 否 | 结果所属的平台，例如 `instagram` 或 `linkedin`。 |
| `resource` | `string` | 否 | 该结果对应的 SocQ 资源，例如 `videos` 或 `comments`。 |
| `type` | `string` | 否 | 结果项的类别，例如 `video`、`post` 或 `comment`。 |
| `url` | `string` | 是 | 结果项的公开访问地址（如可获得）。 |
| `published_at` | `string` | 是 | 源内容的发布时间（如可获得），使用 ISO 8601 格式。 |
| `collected_at` | `string` | 否 | SocQ 采集或处理该结果的时间，使用 ISO 8601 格式。 |
| `name` | `string` | 是 | 原声或歌曲标题。 |
| `text` | `string` | 是 | 原声的显示标题。 |
| `author` | `object` | 是 | 内容的作者或发布者。 |
| `author.id` | `string` | 是 | 作者的唯一标识。 |
| `author.username` | `string` | 是 | 账号的公开用户名或账号标识。 |
| `author.name` | `string` | 是 | 作者的显示名称。 |
| `author.url` | `string` | 是 | 作者的公开访问地址（如可获得）。 |
| `author.avatar_url` | `string` | 是 | 账号头像图片的地址。 |
| `author.is_verified` | `boolean` | 是 | 账号是否已通过平台认证。 |
| `author.is_private` | `boolean` | 是 | 账号是否为私密账号。 |
| `cover_url` | `string` | 是 | 封面图片的地址。 |
| `duration_seconds` | `number` | 是 | 时长，单位为秒。 |
| `audio` | `object` | 是 | 原声的可播放预览。 |
| `audio.id` | `string` | 是 | 音频或音乐曲目的标识。 |
| `audio.title` | `string` | 是 | 音频或音乐曲目的标题。 |
| `audio.artist` | `string` | 是 | 音频艺术家或创作者名称。 |
| `audio.url` | `string` | 是 | 音频或音乐曲目的地址（如可获得）。 |
| `metrics` | `object` | 是 | 结果项可获得的计数和度量数据。 |
| `metrics.videos_count` | `integer` | 是 | 使用该原声的视频数量。 |
## 任务完成响应
```json theme={"system"}
{
"code": 200,
"data": {
"task_id": "A1B2C3D4E5F6G7H8",
"status": "succeeded",
"public_id": "tiktok/song",
"result_count": 1,
"credits_amount": 0.5,
"results": {
"limit": 1,
"next_cursor": null,
"has_more": false,
"schema_id": "music",
"schema_version": "1.0",
"items": [
{
"id": "7439295283975702544",
"platform": "tiktok",
"resource": "song",
"type": "music",
"url": "https://www.tiktok.com/music/luther-7439295283975702544?_r=1&sharer_language=en&source=h5_m&u_code=f117aka677jbg0&_d=f117ab8kmc1a35&share_music_id=7439295283975702544",
"published_at": "2024-11-22T23:15:12Z",
"collected_at": "2026-09-12T07:00:00Z",
"name": "luther",
"text": "luther",
"author": {
"id": "7486547994222740523",
"username": "sza",
"name": "SZA",
"url": "https://www.tiktok.com/@sza",
"avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/42b31651a14a0f2151814dcbace36525~tplv-tiktokx-cropcenter:168:168.webp?dr=10397&refresh_token=0b46c746&x-expires=1789279200&x-signature=GTH4ZSqgLr9oVvqKbH5yrs65DQ8%3D&t=4d5b0474&ps=13740610&shp=544a444f&shcp=f6441914&idc=no1a",
"is_verified": null,
"is_private": null
},
"cover_url": "https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/ooCBAEtE4DqIfBLAjADiRIneQATZEYFgAh8tm8.jpeg",
"duration_seconds": 59.0,
"audio": {
"id": "7439295283975702544",
"title": "luther",
"artist": "SZA",
"url": "https://sf19-music.tiktokcdn-eu.com/obj/tos-alisg-ve-2774/o8f9CfEFDdCEDUAq6gDqgOY4gQNfJHzxhF2ayE"
},
"metrics": {
"videos_count": 1424364
}
}
]
}
}
}
```
## OpenAPI
````yaml zh/api-manual/agent-api/agent-api.json POST /v1/tiktok/song
openapi: 3.1.0
info:
title: SocQ Agent API 中文版
version: v1-c801a6d1844b
description: 根据 SocQ 能力目录生成的异步社交数据 API。
servers:
- url: https://api.socq.ai
security: []
paths:
/v1/tiktok/song:
post:
tags:
- tiktok
summary: TikTok 原声
description: 按 clip ID 或 URL 采集公开 TikTok 音乐与原声元数据。
operationId: socq_tiktok_song
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
additionalProperties: false
properties:
callback_url:
type: string
format: uri
description: 可选的任务完成回调 URL。
music_id:
type: string
minLength: 1
description: TikTok 原声 ID，来自音乐页面 URL 中的数字标识。
url:
type: string
minLength: 1
description: 公开内容、主页或商品 URL。
required: []
anyOf:
- required:
- music_id
- required:
- url
responses:
'200':
description: 任务已受理
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubmitResponse'
'422':
description: Input validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/AgentValidationErrorResponse'
security:
- bearerAuth: []
- apiKeyAuth: []
components:
schemas:
AgentSubmitResponse:
type: object
properties:
code:
type: integer
const: 200
description: HTTP 业务状态码。
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于查询任务状态和结果。
status:
type: string
description: 任务当前状态。
created_time:
type:
- string
- 'null'
description: 任务创建时间。
required:
- task_id
- status
AgentValidationErrorResponse:
type: object
properties:
code:
type: integer
const: 422
error:
type: object
properties:
message:
type: string
type:
type: string
details:
type: object
required:
- message
- type
required:
- code
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: '使用 `Authorization: Bearer ` 请求头进行身份验证。'
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: 也可以通过 `x-api-key` 请求头提供 API Key。
````