# 导出投稿作品列表/Download item list ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/v1/douyin/creator_v2/fetch_item_list_download: post: summary: 导出投稿作品列表/Download item list deprecated: false description: >- # [中文] ### 用途: - 导出指定时间范围内前1000条投稿作品的详细数据 - 支持按体裁类型筛选导出内容 - **此接口用于批量导出数据，不适合实时查询** - **导出任务为异步处理，需要等待服务器生成文件** - **此接口需要用户提供有效的抖音创作者平台Cookie** - **使用 POST 方法，Cookie 在请求体中传输，更安全** ### 请求体参数: - cookie: 用户的抖音创作者平台Cookie（必填，在请求体中传输） - min_cursor: 最小游标，即开始时间戳（毫秒）（必填） - max_cursor: 最大游标，即结束时间戳（毫秒）（必填） - type_filters: 体裁类型过滤列表，默认全选 [1,2,3,4,5,8]（可选） - **1**: 1分钟以内视频 - **2**: 1-3分钟视频 - **3**: 3-5分钟视频 - **4**: 5分钟以上视频 - **5**: 图文作品 - **8**: 长图文作品 - need_long_article: 是否包含长图文，默认true（可选） ### 返回: - **直接返回Excel文件流**，浏览器会自动下载 - 文件名：作品列表导出.xlsx - 文件格式：Excel (.xlsx) - Content-Type: application/vnd.ms-excel ### 使用流程: 1. **发起导出请求**：提交时间范围和筛选条件 2. **接收文件**：接口会直接返回Excel文件流 3. **自动下载**：浏览器会自动触发文件下载 4. **数据分析**：打开Excel文件进行数据分析 ### 功能限制: - 仅支持导出：所选周期内，前1000条作品的数据 - 支持按体裁类型筛选（可选择1-6种体裁的任意组合） - 不支持实时查询，适合批量数据分析场景 ### 体裁类型说明: | 类型值 | 体裁名称 | 说明 | 使用场景 | |-------|---------|------|---------| | 1 | 1min以内视频 | 短视频 | 快速传播，高互动 | | 2 | 1-3min视频 | 中短视频 | 平衡内容与时长 | | 3 | 3-5min视频 | 中长视频 | 深度内容呈现 | | 4 | 5min+视频 | 长视频 | 专业内容，深度分析 | | 5 | 图文 | 图文作品 | 图片+文字形式 | | 8 | 长图文 | 长图文作品 | 深度图文内容 | ### 导出数据包含: - 作品基本信息（ID、标题、发布时间等） - 流量指标（播放量、点赞量、评论量、分享量、收藏量） - 审核状态 - 可见性设置 - 其他创作者相关数据 ### 时间戳转换: - JavaScript: `new Date('2025-07-01').getTime()` -> 1719763200000 - Python: `int(datetime(2025, 7, 1).timestamp() * 1000)` -> 1719763200000 ### Cookie 获取方式: 1. 登录抖音创作者平台 (https://creator.douyin.com) 2. 打开浏览器开发者工具（F12） 3. 切换到 Network 标签 4. 刷新页面或进行操作 5. 找到任意请求，复制 Cookie 请求头的值 # [English] ### Purpose: - Export detailed data of top 1000 items within the specified time range - Support filtering export content by genre types - **This API is for batch export, not suitable for real-time queries** - **Export tasks are processed asynchronously, need to wait for server to generate file** - **This API requires users to provide valid Douyin Creator Platform Cookie** - **Use POST method, Cookie is transmitted in request body, more secure** ### Request Body Parameters: - cookie: User's Douyin Creator Platform Cookie (required, transmitted in request body) - min_cursor: Min cursor, i.e., start timestamp in milliseconds (required) - max_cursor: Max cursor, i.e., end timestamp in milliseconds (required) - type_filters: Genre type filter list, default all [1,2,3,4,5,8] (optional) - **1**: Videos under 1 minute - **2**: 1-3 minute videos - **3**: 3-5 minute videos - **4**: Videos over 5 minutes - **5**: Image posts - **8**: Long image posts - need_long_article: Include long articles, default true (optional) ### Return: - **Directly returns Excel file stream**, browser will auto-download - Filename: 作品列表导出.xlsx (Item List Export.xlsx) - File Format: Excel (.xlsx) - Content-Type: application/vnd.ms-excel ### Usage Flow: 1. **Initiate export request**: Submit time range and filter conditions 2. **Receive file**: API returns Excel file stream directly 3. **Auto download**: Browser automatically triggers file download 4. **Data analysis**: Open Excel file for data analysis ### Limitations: - Only supports exporting: Top 1000 items in selected period - Support filtering by genre types (can select any combination of 1-6 genres) - Not suitable for real-time queries, designed for batch data analysis ### Genre Type Description: | Type | Genre Name | Description | Use Case | |------|-----------|-------------|----------| | 1 | <1min video | Short video | Fast spread, high engagement | | 2 | 1-3min video | Medium-short video | Balance content & duration | | 3 | 3-5min video | Medium-long video | Deep content presentation | | 4 | 5min+ video | Long video | Professional content, deep analysis | | 5 | Image post | Image post | Picture + text format | | 8 | Long image post | Long image post | Deep image-text content | ### Export Data Includes: - Item basic info (ID, title, publish time, etc.) - Traffic metrics (views, likes, comments, shares, favorites) - Review status - Visibility settings - Other creator-related data ### Timestamp Conversion: - JavaScript: `new Date('2025-07-01').getTime()` -> 1719763200000 - Python: `int(datetime(2025, 7, 1).timestamp() * 1000)` -> 1719763200000 ### How to get Cookie: 1. Login to Douyin Creator Platform (https://creator.douyin.com) 2. Open browser developer tools (F12) 3. Switch to Network tab 4. Refresh page or perform operations 5. Find any request and copy the Cookie header value # [示例/Example] ### 导出所有体裁/Export All Genres: ```json { "cookie": "Your_Cookie_Here", "min_cursor": 1752336000000, "max_cursor": 1760198399000, "type_filters": [1, 2, 3, 4, 5, 8], "need_long_article": true } ``` ### 仅导出视频作品/Export Only Videos: ```json { "cookie": "Your_Cookie_Here", "min_cursor": 1752336000000, "max_cursor": 1760198399000, "type_filters": [1, 2, 3, 4], "need_long_article": false } ``` ### 仅导出图文作品/Export Only Image Posts: ```json { "cookie": "Your_Cookie_Here", "min_cursor": 1752336000000, "max_cursor": 1760198399000, "type_filters": [5, 8], "need_long_article": true } ``` ### 返回数据说明/Response Description: - 此接口直接返回Excel文件流，不返回JSON数据 - 响应头包含 `Content-Disposition: attachment; filename="作品列表导出.xlsx"` - 浏览器会自动识别并触发文件下载 - 文件内容为二进制流（application/vnd.ms-excel） ### 使用方式示例/Usage Examples: **使用 cURL 下载:** ```bash curl -X POST "https://your-api.com/api/v1/douyin_creator_v2/fetch_item_list_download" -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{ "cookie": "Your_Cookie_Here", "min_cursor": 1752336000000, "max_cursor": 1760198399000, "type_filters": [1,2,3,4,5,8] }' -o "作品列表导出.xlsx" ``` **使用 Python requests:** ```python import requests response = requests.post( "https://your-api.com/api/v1/douyin_creator_v2/fetch_item_list_download", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "cookie": "Your_Cookie_Here", "min_cursor": 1752336000000, "max_cursor": 1760198399000, "type_filters": [1,2,3,4,5,8] } ) # 保存文件 with open("作品列表导出.xlsx", "wb") as f: f.write(response.content) ``` **使用 JavaScript (Axios):** ```javascript const axios = require('axios'); const fs = require('fs'); axios.post('https://your-api.com/api/v1/douyin_creator_v2/fetch_item_list_download', { cookie: 'Your_Cookie_Here', min_cursor: 1752336000000, max_cursor: 1760198399000, type_filters: [1,2,3,4,5,8] }, { headers: { 'Authorization': 'Bearer YOUR_TOKEN' }, responseType: 'arraybuffer' }).then(response => { fs.writeFileSync('作品列表导出.xlsx', response.data); }); ``` ### 注意事项/Notes: 1. **数据量限制**: 最多导出前1000条作品数据 2. **即时生成**: 接口会立即生成Excel文件并返回，无需等待 3. **时间范围**: 建议不要设置过长的时间范围，以免数据量过大导致超时 4. **体裁筛选**: 可以根据分析需求选择特定体裁类型 5. **文件格式**: Excel (.xlsx) 格式，兼容 Microsoft Excel、WPS、Google Sheets等 6. **响应类型**: 返回二进制流，不是JSON，请使用正确的响应处理方式 7. **Cookie有效性**: 如果返回错误，请检查Cookie是否过期 8. **超时设置**: 建议设置较长的超时时间（60秒以上），因为需要生成文件 9. **文件编码**: 文件名使用UTF-8编码，支持中文显示 operationId: >- fetch_item_list_download_api_v1_douyin_creator_v2_fetch_item_list_download_post tags: - Douyin-Creator-V2-API - Douyin-Creator-V2-API parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ItemListDownloadRequest' description: 投稿作品列表导出请求参数/Item list download request parameters example: cookie: Your_Cookie_Here min_cursor: 1752336000000 max_cursor: 1760198399000 type_filters: - 2 - 3 - 4 - 5 - 1 - 8 need_long_article: true responses: '200': description: Successful Response content: application/json: schema: type: string headers: {} x-apifox-name: OK '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' headers: {} x-apifox-name: Unprocessable Entity security: - HTTPBearer: [] x-apifox: schemeGroups: - id: mndvwvNjI_4jXUuxQK40H schemeIds: - HTTPBearer required: true use: id: mndvwvNjI_4jXUuxQK40H scopes: mndvwvNjI_4jXUuxQK40H: HTTPBearer: [] x-apifox-folder: Douyin-Creator-V2-API x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/4705614/apis/api-359719872-run components: schemas: ItemListDownloadRequest: properties: cookie: type: string title: Cookie description: 用户Cookie/User Cookie examples: - Your_Cookie_Here min_cursor: type: integer title: Min Cursor description: 最小游标(开始时间戳,毫秒)/Min cursor (start timestamp in milliseconds) examples: - 1752336000000 max_cursor: type: integer title: Max Cursor description: 最大游标(结束时间戳,毫秒)/Max cursor (end timestamp in milliseconds) examples: - 1760198399000 type_filters: items: type: integer type: array title: Type Filters description: >- 体裁类型过滤/Type filters: 1=1min以内视频, 2=1-3min视频, 3=3-5min视频, 4=5min+视频, 5=图文, 8=长图文 default: - 1 - 2 - 3 - 4 - 5 - 8 examples: - - 2 - 3 - 4 - 5 - 1 - 8 need_long_article: type: boolean title: Need Long Article description: 是否包含长图文/Include long articles default: true examples: - true type: object required: - cookie - min_cursor - max_cursor title: ItemListDownloadRequest description: |- 投稿作品列表导出请求模型 Item List Download Request Model x-apifox-orders: - cookie - min_cursor - max_cursor - type_filters - need_long_article x-apifox-ignore-properties: [] x-apifox-folder: '' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError x-apifox-orders: - detail x-apifox-ignore-properties: [] x-apifox-folder: '' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError x-apifox-orders: - loc - msg - type x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: HTTPBearer: type: bearer description: > ---- #### API Token Introduction: ##### Method 1: Use API Token in the Request Header (Recommended) - **Header**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: Click on the `Authorize` button in the upper right corner of the page to enter the API token directly without the `Bearer` keyword. ##### Method 2: Use API Token in the Cookie (Not Recommended, Use Only When Method 1 is Unavailable) - **Cookie**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `Authorization=Bearer your_token` #### Get API Token: 1. Register and log in to your account on the TikHub website. 2. Go to the user center, click on the API token menu, and create an API token. 3. Copy and use the API token in the request header. 4. Keep your API token confidential and use it only in the request header. ---- #### API令牌简介: ##### 方法一：在请求头中使用API令牌（推荐） - **请求头**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: 点击页面右上角的`Authorize`按钮，直接输入API令牌，不需要`Bearer`关键字。 ##### 方法二：在Cookie中使用API令牌（不推荐，仅在无法使用方法一时使用） - **Cookie**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `Authorization=Bearer your_token` #### 获取API令牌: 1. 在TikHub网站注册并登录账户。 2. 进入用户中心，点击API令牌菜单，创建API令牌。 3. 复制并在请求头中使用API令牌。 4. 保密您的API令牌，仅在请求头中使用。 scheme: bearer servers: - url: https://api.tikhub.io description: Production Environment security: [] ```