TikTok API Documentation

TikTok supports two content types:

Recommended Video Specs

Video Cover (Thumbnail)

Customize which frame appears as the thumbnail:

{
  "tiktokSettings": {
    "video_cover_timestamp_ms": 3000
  }
}

• • Value in milliseconds
• • Default: 0 (start)
• • Must be within video duration

Create photo slideshows with up to 35 images.

Photo Requirements

Cover Photo

Set which photo appears as the cover:

{
  "tiktokSettings": {
    "photo_cover_index": 0  // 0 = first photo
  }
}

Let TikTok automatically add recommended music to photo carousels:

{
  "tiktokSettings": {
    "auto_add_music": true // Default: true for photos
  }
}

Disclose AI-generated content to comply with TikTok policies:

{
  "tiktokSettings": {
    "video_made_with_ai": true
  }
}

Send content to Creator's TikTok Inbox as a draft instead of publishing immediately. Works for both video and photo posts.

Usage

Add draft: true to your tiktokSettings:

// Video Draft
{
  "accountId": "YOUR_ACCOUNT_ID",
  "content": "My video caption",
  "mediaItems": [
    { "url": "https://your-domain.com/video.mp4" }
  ],
  "tiktokSettings": {
    "draft": true
  }
}

// Photo Draft
{
  "accountId": "YOUR_ACCOUNT_ID",
  "content": "Photo description",
  "mediaItems": [
    { "url": "https://your-domain.com/photo1.jpg" },
    { "url": "https://your-domain.com/photo2.jpg" }
  ],
  "tiktokSettings": {
    "media_type": "photo",
    "draft": true,
    "privacy_level": "PUBLIC_TO_EVERYONE"
  }
}

How It Works

These fields are required for all posts:

Connect TikTok accounts via QR code scan — no browser redirect needed.
The user scans the QR code with their TikTok app and confirms the authorization. This method is ideal if you want to integrate our platform into your own custom application, allowing your users to link their TikTok accounts seamlessly from within your app.

1. Request QR Code

Request Body (optional)

{
  "unique_id": "my_session_12345"  // Optional, min 8 chars. Auto-generated if not provided.
}

Example Request

// Step 1: Request QR Code
fetch('https://api-tiktok.wahdx.co/api/content/qr-login/request', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    unique_id: 'my_session_12345' // Optional, min 8 chars
  })
})

Success Response (200)

{
  "success": true,
  "data": {
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
    "token": "VJ5JCKGJGRSWNMFWHQH4W5NKY943Q97D",
    "unique_id": "my_session_12345",
    "expiresIn": 300
  }
}

{
  "error": "QR Code login is only available for Maximum subscription",
  "subscription": "free"
}

2. Check QR Status

Request Body

{
  "token": "VJ5JCKGJGRSWNMFWHQH4W5NKY943Q97D"  // Required: token from Step 1
}

Example Request

// Step 2: Poll QR Status (every 3 seconds)
fetch('https://api-tiktok.wahdx.co/api/content/qr-login/check', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: 'TOKEN_FROM_STEP_1'
  })
})

Response by Status

{ "success": true, "data": { "status": "new", "unique_id": "my_session_12345" } }

{ "success": true, "data": { "status": "scanned", "unique_id": "my_session_12345" } }

{
  "success": true,
  "data": {
    "status": "confirmed",
    "unique_id": "my_session_12345",
    "account": {
      "accountId": "8abd72f0-4ede-441c-9c17-XXXXXXXXX",
      "display_name": "Creator Name",
      "username": "creator_username"
    }
  }
}

{ "success": true, "data": { "status": "expired", "unique_id": "my_session_12345" } }

{ "success": true, "data": { "status": "utilised", "unique_id": "...", "message": "QR code has already been used." } }

3. Check List Account

{
  "success": true,
  "subscription": "maximum",
  "data": [
    {
      "accountId": "aada5586-xxxx-xxxx-xxxx-XXXXXXXXXXX",
      "display_name": "Account 1",
      "username": "account_1",
      "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-...",
      "bio_description": "My awesome bio",
      "followers": 1500,
      "following": 300,
      "likes": 12500,
      "videos": 42,
      "is_verified": false
    },
    {
      "accountId": "8abd72f0-xxxx-xxxx-xxxx-XXXXXXXXXXX",
      "display_name": "Account 2",
      "username": "account_2"
    },
    {
      "accountId": "23369e89-xxxx-xxxx-xxxx-XXXXXXXXXXX",
      "display_name": "Account 3",
      "username": "account_3"
    }
  ]
}

Complete Example

// Complete QR Login Flow
async function loginWithQR(apiKey) {
  // Step 1: Request QR Code
  const qr = await fetch('https://api-tiktok.wahdx.co/api/content/qr-login/request', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ unique_id: 'session_' + Date.now() })
  }).then(r => r.json());

  // Display QR: <img src={qr.data.qrCodeImage} />
  console.log('Scan this QR code with TikTok app');

  // Step 2: Poll status every 10 seconds
  const poll = setInterval(async () => {
    const check = await fetch('https://api-tiktok.wahdx.co/api/content/qr-login/check', {
      method: 'POST',
      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: qr.data.token })
    }).then(r => r.json());

    if (check.data.status === 'confirmed') {
      clearInterval(poll);
      console.log('Account linked!', check.data.account);
    } else if (['expired', 'utilised'].includes(check.data.status)) {
      clearInterval(poll);
      console.log('QR expired, request a new one');
    }
  }, 10000);
}

{
  "success": true,
  "data": {
    "publish_id": "v_pub_url~v2.123456789",
    "public_post_url": "https://www.tiktok.com/@user/video/1234567890" // Only available after processing
  },
  "mediaType": "video"
}