Skip to main content

​
Upload API Reference

Upload videos and photo carousels to your TikTok accounts programmatically using our Upload API.

​
Base Endpoint

POST /api/v1/upload

​
Authentication

  • Required: Bearer token (JWT or API key)
  • Feature: Available to all subscription plans

​
Endpoints

​
Upload Video

POST /api/v1/upload/video Upload a video directly or from a URL.
​
tiktokAccountId
string
TikTok account ID to upload to. Auto-selected if only one account connected.
​
title
string
required
Video title (1-150 characters)
​
description
string
Video description (max 2200 characters)
​
privacyLevel
string
default:"PUBLIC_TO_EVERYONE"
Privacy level:
  • PUBLIC_TO_EVERYONE
  • MUTUAL_FOLLOW_FRIENDS
  • FOLLOWER_OF_CREATOR
  • SELF_ONLY
​
disableDuet
boolean
default:"false"
Disable duet functionality
​
disableStitch
boolean
default:"false"
Disable stitch functionality
​
disableComment
boolean
default:"false"
Disable comments
​
videoCoverTimestampMs
integer
Custom video cover timestamp in milliseconds
​
videoUrl
string
Direct video URL for URL-based uploads
curl -X POST 'https://api.d1g.qzz.io/api/v1/upload/video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My Amazing Video",
    "description": "Check out this awesome content!",
    "privacyLevel": "PUBLIC_TO_EVERYONE",
    "disableDuet": false,
    "disableStitch": false,
    "videoUrl": "https://example.com/video.mp4"
  }'

import axios from 'axios';

const uploadVideo = async () => {
  try {
    const response = await axios.post(
      'https://api.d1g.qzz.io/api/v1/upload/video',
      {
        title: 'My Amazing Video',
        description: 'Check out this awesome content!',
        privacyLevel: 'PUBLIC_TO_EVERYONE',
        disableDuet: false,
        disableStitch: false,
        videoUrl: 'https://example.com/video.mp4'
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Upload successful:', response.data);
  } catch (error) {
    console.error('Upload failed:', error.response?.data || error.message);
  }
};

import requests

def upload_video():
    url = "https://api.d1g.qzz.io/api/v1/upload/video"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    data = {
        "title": "My Amazing Video",
        "description": "Check out this awesome content!",
        "privacyLevel": "PUBLIC_TO_EVERYONE",
        "disableDuet": False,
        "disableStitch": False,
        "videoUrl": "https://example.com/video.mp4"
    }
    
    response = requests.post(url, json=data, headers=headers)
    
    if response.status_code == 200:
        print("Upload successful:", response.json())
    else:
        print("Upload failed:", response.json())

{
  "success": true,
  "data": {
    "uploadId": "dd3c9a25-f6a0-4ef7-b227-830fa0da70e4",
    "status": "pending",
    "message": "Video upload queued. Processing in background."
  }
}
POST /api/v1/upload/photo Upload a photo carousel with 1-35 photos.
​
tiktokAccountId
string
TikTok account ID to upload to
​
title
string
required
Carousel title (1-150 characters)
​
privacyLevel
string
default:"PUBLIC_TO_EVERYONE"
Privacy level (same options as video upload)
​
disableDuet
boolean
default:"false"
Disable duet functionality
​
disableStitch
boolean
default:"false"
Disable stitch functionality
​
disableComment
boolean
default:"false"
Disable comments
​
photoCount
integer
required
Number of photos in carousel (1-35)
Photo uploads require multipart/form-data encoding with photos sent as file fields named photos[].

​
Get Upload Status

GET /api/v1/upload/status/{uploadId} Get the current status of an upload.
​
uploadId
string
required
Upload ID returned from upload endpoint
{
  "success": true,
  "data": {
    "uploadId": "dd3c9a25-f6a0-4ef7-b227-830fa0da70e4",
    "status": "published",
    "progressPercentage": 100,
    "tiktokVideoId": "v_inbox_file~v2.7562847402311370807",
    "error": null,
    "mediaType": "video",
    "publishedAt": "2025-01-19T09:31:40.733Z"
  }
}

​
Get Upload History

GET /api/v1/upload/history Get a list of all uploads for the authenticated user. 
{
  "success": true,
  "data": [
    {
      "id": "dd3c9a25-f6a0-4ef7-b227-830fa0da70e4",
      "tiktokVideoId": "v_inbox_file~v2.7562847402311370807",
      "title": "Amazing TikTok Video",
      "description": "Check out this amazing content!",
      "status": "published",
      "uploadProgress": 100,
      "mediaType": "video",
      "tiktokAccount": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "my_tiktok_handle",
        "displayName": "My TikTok Name"
      },
      "createdAt": "2025-01-19T09:31:29.265Z",
      "publishedAt": "2025-01-19T09:31:40.733Z",
      "error": null
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

​
Delete Upload

DELETE /api/v1/upload/{uploadId} Delete an upload (only works for uploads that haven’t been published).
​
uploadId
string
required
Upload ID to delete

​
Upload Limits

PlanMonthly LimitVideo SizePhoto Count
Free51GB1-35
Basic251GB1-35
Professional1001GB1-35
Exceeding upload limits will result in a 403 FORBIDDEN error. Upload limits reset on your subscription anniversary date.

​
Common Errors

  • 400 VALIDATION_ERROR: Invalid parameters or missing required fields
  • 403 FORBIDDEN: Upload limit exceeded or insufficient permissions
  • 404 NOT_FOUND: Invalid upload ID
  • 413 PAYLOAD_TOO_LARGE: File size exceeds 1GB limit
  • 422 UNPROCESSABLE_ENTITY: Unsupported file format or corrupted file
For file upload errors, ensure your video is in MP4 format with H.264 codec and your photos are JPG/PNG under 10MB each.