TikTok Content Posting API大文件分片上传初始化失败求助

1. 强制合规分片大小 #

TikTok API要求分片大小必须是5MB的整数倍，单分片最大不超过64MB。很多400错误源于分片大小不符合规范，直接固定分片值：

const CHUNK_SIZE = 5 * 1024 * 1024; // 固定5MB，别用其他非5MB倍数的数值

2. 校验分片请求核心头信息 #

每个分片请求必须携带以下关键头，缺漏或格式错误直接触发400：

• Content-Type: 必须是视频实际MIME类型（如video/mp4），不能填multipart/form-data或其他值
• Content-Range: 严格遵循bytes start-end/total格式，比如第一片为bytes 0-5242879/123456789（start从0开始，end为CHUNK_SIZE-1，total是文件总字节数）
• X-TikTok-Session-Id: 必须和初始化上传接口返回的会话ID完全一致

3. 修正分片上传逻辑细节 #

• 分片索引从0开始计数，别搞成从1开始
• 最后一片如果不足5MB，无需补全字节，直接传实际剩余内容，同时更新Content-Range的end值为总字节数-1
• 确保所有分片按顺序上传，不能跳传或重复上传

4. 初始化上传参数必须精准 #

调用/video/upload/init/接口时，以下参数不能出错：

• file_size: 必须是文件实际总字节数，用fs.statSync(filePath).size精确获取，不能估算
• file_name: 带后缀的完整文件名（如test.mp4），TikTok会据此校验格式
• mime_type: 和分片请求的Content-Type保持一致

5. 错误排查关键动作 #

如果仍报400，打印每个分片请求的完整请求头、Content-Range值、分片字节数，重点检查：

• Content-Range的end是否超过文件总字节数
• 初始化会话ID是否在所有分片请求中一致
• 是否有分片漏传或重复上传

修正后的分片上传代码片段 #

const fs = require('fs');
const axios = require('axios');

const CHUNK_SIZE = 5 * 1024 * 1024;
const filePath = './large_video.mp4';
const fileStats = fs.statSync(filePath);
const totalBytes = fileStats.size;
const sessionId = '从初始化接口获取的会话ID';
const accessToken = '你的TikTok接口访问令牌';

async function uploadChunks() {
  let start = 0;
  let chunkIndex = 0;

  while (start < totalBytes) {
    const end = Math.min(start + CHUNK_SIZE - 1, totalBytes - 1);
    const chunk = fs.readFileSync(filePath, { start, end });

    try {
      await axios.post('https://open-api.tiktok.com/video/upload/chunk/', chunk, {
        headers: {
          'Content-Type': 'video/mp4',
          'Content-Range': `bytes ${start}-${end}/${totalBytes}`,
          'X-TikTok-Session-Id': sessionId,
          'Authorization': `Bearer ${accessToken}`
        }
      });
      console.log(`分片 ${chunkIndex} 上传成功`);
    } catch (err) {
      console.error(`分片 ${chunkIndex} 失败:`, err.response?.data || err.message);
      throw err;
    }

    start = end + 1;
    chunkIndex++;
  }

  // 触发上传完成
  await axios.post('https://open-api.tiktok.com/video/upload/finish/', {
    session_id: sessionId,
    file_name: 'large_video.mp4'
  }, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
}

内容的提问来源于stack exchange，提问作者Deepak Anand