服务正常 · 无需鉴权

抖音视频、图集与实况解析 API

一个接口自动识别普通视频、图文作品和 Live Photo 实况照片。响应中的 type 是业务分流依据；实况作品保持 gallery，并通过 mediaType: live_photo 识别。

调用地址

GET

参数值必须进行 URL 编码。可传短链接、作品页链接，或完整分享文字中的抖音链接。

请求参数

请求方法为 GET，响应编码为 UTF-8，Content-Type 为 application/json。

参数	类型	必填	说明	示例
`url`	string	是	抖音分享短链、视频链接或图文链接。调用方应先提取分享文字中的 URL。	`https://v.douyin.com/xxx/`

在线调试

输入真实链接直接请求当前 API，结果会在下方显示。

抖音链接

等待请求

响应格式

type: video

视频响应

使用 url 播放或下载视频，images 固定为空数组。

type: gallery

图集与实况响应

遍历 images；mediaType=image 为静态图，live_photo 时读取每项的 videoUrl。

成功响应示例

200 · video

{
  "code": 200,
  "type": "video",
  "videoId": "7520000000000000000",
  "title": "作品标题",
  "author": "作者昵称",
  "url": "https://video-cdn.example.com/video.mp4",
  "cover": "",
  "images": [],
  "imageCount": 0,
  "sourceUrl": "https://www.iesdouyin.com/share/video/752.../",
  "cached": false
}

200 · gallery

{
  "code": 200,
  "type": "gallery",
  "mediaType": "image",
  "videoId": "7662259898261030499",
  "title": "#周末去哪儿 #昆明旅游",
  "author": "作者昵称",
  "url": "",
  "cover": "https://p3-sign.douyinpic.com/cover.webp",
  "images": [
    {
      "url": "https://p3-sign.douyinpic.com/image-1.webp",
      "width": 880,
      "height": 1168
    }
  ],
  "imageCount": 1,
  "livePhotoCount": 0,
  "sourceUrl": "https://www.iesdouyin.com/share/note/766.../",
  "cached": false
}

200 · gallery / live_photo

{
  "code": 200,
  "type": "gallery",
  "mediaType": "live_photo",
  "videoId": "7519121325147933952",
  "title": "实况照片作品",
  "author": "作者昵称",
  "url": "",
  "cover": "https://p3-sign.douyinpic.com/image-1.webp",
  "images": [
    {
      "url": "https://p3-sign.douyinpic.com/image-1.webp",
      "width": 1080,
      "height": 1440,
      "videoUrl": "https://video-cdn.example.com/live-1.mp4",
      "duration": 2485,
      "videoWidth": 720,
      "videoHeight": 960
    }
  ],
  "imageCount": 1,
  "livePhotoCount": 1,
  "sourceUrl": "https://www.iesdouyin.com/share/note/751.../",
  "cached": false
}

字段说明

字段	类型	适用类型	说明
`code`	integer	全部	业务状态码。200 成功，400 参数错误，500 解析失败。
`type`	string	全部	`video`、`gallery` 或 `error`。调用方应优先判断此字段。
`videoId`	string	视频/图集	抖音作品数字 ID。字段名为兼容旧版保留，图集同样返回。
`title`	string	视频/图集	作品标题或描述。上游缺失时可能为“未知标题”。
`author`	string	视频/图集	作者昵称。上游缺失时可能为“未知作者”。
`url`	string	视频	视频播放/下载直链。图集响应中为空字符串。
`cover`	string	视频/图集	封面地址。当前图集为首图，视频可能为空。
`images`	array	图集	图片对象数组，视频响应中固定为空数组。
`images[].url`	string	图集	原始图片地址。地址包含有效期，建议按需使用，不要永久存储。
`images[].width`	integer	图集	图片原始宽度，单位像素。
`images[].height`	integer	图集	图片原始高度，单位像素。
`mediaType`	string	图集	`image` 为静态图集，`live_photo` 为包含实况视频的图集。
`images[].videoUrl`	string	实况图集	该图片对应的有声 MP4 地址；普通静态图片不返回此字段。
`images[].duration`	integer	实况图集	实况视频时长，单位毫秒。
`images[].videoWidth`	integer	实况图集	实况 MP4 画面宽度，单位像素。
`images[].videoHeight`	integer	实况图集	实况 MP4 画面高度，单位像素。
`livePhotoCount`	integer	图集	图集中已解析到的实况 MP4 数量。
`imageCount`	integer	视频/图集	图片数量。视频固定为 0。
`sourceUrl`	string	视频/图集/错误	短链接重定向后的抖音作品页，用于追踪来源。
`cached`	boolean	视频/图集	是否命中服务端缓存。图集当前固定为 false。
`error`	string	错误	可直接展示给开发者的错误原因。

错误处理

400缺少 url 参数，或链接不是有效的抖音域名。

500上游页面结构变化、作品不可访问、链接失效或未提取到媒体地址。

错误响应

业务错误

{
  "code": 400,
  "type": "error",
  "error": "请提供 url 参数"
}

当前接口通过 JSON 内的 code 表示业务状态，HTTP 状态通常为 200。接入时不要只判断 HTTP 状态。

调用示例

cURL

Shell

curl --get \
  --data-urlencode "url=https://v.douyin.com/xxxx/" \
  ""

JavaScript

Fetch

const shareUrl = 'https://v.douyin.com/xxxx/';
const endpoint = new URL('');
endpoint.searchParams.set('url', shareUrl);

const data = await fetch(endpoint).then(r => r.json());
if (data.code !== 200) throw new Error(data.error);

if (data.type === 'video') {
  console.log(data.url);
} else if (data.type === 'gallery') {
  data.images.forEach(image => {
    console.log('静态图', image.url);
    if (image.videoUrl) console.log('实况 MP4', image.videoUrl);
  });
}

Python

Requests

import requests

response = requests.get(
    '',
    params={'url': 'https://v.douyin.com/xxxx/'},
    timeout=45,
)
data = response.json()

if data['code'] != 200:
    raise RuntimeError(data['error'])

if data['type'] == 'video':
    media_urls = [data['url']]
else:
    media_urls = [
        image.get('videoUrl') or image['url']
        for image in data['images']
    ]

接入须知

推荐判断顺序：先判断 code === 200，再按 type 分流；当 type === gallery 时继续判断 mediaType。实况作品中每张图的 videoUrl 是独立有声 MP4，不是 GIF，也不要使用顶层配乐代替。媒体 CDN 地址可能过期，不建议长期持久化。解析耗时受抖音上游网络影响，客户端超时建议设置为 60 秒。