🎵 TikTok Content Posting API

Tudo começa em developers.tiktok.com. Crie uma conta TikTok comum primeiro (pessoal ou business), depois faça login no portal e crie um App. Não use a mesma conta que recebe posts: a conta dev é só pra gerenciar credenciais.

Cada App tem Client Key e Client Secret, e precisa declarar quais produtos usa — para postar, é o Content Posting API. Sem ele habilitado, todos os endpoints retornam scope_not_authorized.

# Checklist do portal
1. developers.tiktok.com → Login → Manage Apps
2. Create App
   - Name, description, category, icon (512x512)
   - URL do site (não pode ser localhost em produção)
3. Configuration
   - Redirect URI: https://seu-dominio.com/oauth/tiktok/callback
   - Add Products: Login Kit + Content Posting API
4. Anote Client Key + Client Secret (vai no .env)

# Scopes obrigatórios pra postar
user.info.basic
video.upload         # gera o upload, fica em rascunho
video.publish        # publica direto no feed (precisa de unaudited|audited)

Conceitos-chave

Pra sair de sandbox e atingir contas reais, você submete o App pra audit. TikTok é a plataforma mais rigorosa entre as grandes — recusas são comuns na primeira tentativa. Eles exigem vídeo demo do fluxo, política de privacidade publicada, justificativa escrita do uso de cada scope e, frequentemente, um teste interativo com revisor.

O produto Content Posting API tem dois modos: unaudited (posta como rascunho privado, abre o app pro usuário publicar) e audited (publica direto). Comece pelo unaudited — review mais leve.

Conceitos-chave

A Content Posting API tem dois endpoints distintos, com payloads diferentes. Escolher errado dá 400 invalid_param.

Video Post (/v2/post/publish/video/init/) recebe um único arquivo de vídeo. Photo Post (/v2/post/publish/content/init/ com media_type=PHOTO) recebe URLs públicas de imagens — vira o carrossel/photo mode.

# DIRECT POST (vídeo) — modo PULL_FROM_URL
POST https://open.tiktokapis.com/v2/post/publish/video/init/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "post_info": {
    "title": "Meu vídeo agendado pela API #demo",
    "privacy_level": "SELF_ONLY",      // ou PUBLIC_TO_EVERYONE
    "disable_duet": false,
    "disable_comment": false,
    "disable_stitch": false,
    "video_cover_timestamp_ms": 1000
  },
  "source_info": {
    "source": "PULL_FROM_URL",
    "video_url": "https://cdn.seu-app.com/video.mp4"
  }
}

# PHOTO POST (carrossel) — até 35 fotos
POST https://open.tiktokapis.com/v2/post/publish/content/init/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "media_type": "PHOTO",
  "post_mode": "DIRECT_POST",
  "post_info": {
    "title": "Carrossel da semana",
    "description": "Resumo visual #mkblogs",
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "auto_add_music": true
  },
  "source_info": {
    "source": "PULL_FROM_URL",
    "photo_cover_index": 0,
    "photo_images": [
      "https://cdn.seu-app.com/1.jpg",
      "https://cdn.seu-app.com/2.jpg",
      "https://cdn.seu-app.com/3.jpg"
    ]
  }
}

Conceitos-chave

Quando você não tem CDN pública (ou o vídeo é privado), use FILE_UPLOAD. O fluxo é três passos: init (TikTok devolve upload_url), PUT dos chunks no upload_url, e polling de status até PUBLISH_COMPLETE.

POST /v2/post/publish/video/init/
{
  "source_info": {
    "source": "FILE_UPLOAD",
    "video_size": 47284736,
    "chunk_size": 10000000,
    "total_chunk_count": 5
  }
}
# → { "upload_url": "...", "publish_id": "v_..." }

PUT {upload_url}
Content-Type: video/mp4
Content-Length: 10000000
Content-Range: bytes 0-9999999/47284736

<binary chunk>
# Repita para cada chunk, ajustando o range

POST /v2/post/publish/status/fetch/
{ "publish_id": "v_..." }
# status: PROCESSING_UPLOAD | PROCESSING_DOWNLOAD
#       | PUBLISH_COMPLETE | FAILED

Conceitos-chave

TikTok rejeita silenciosamente vídeos que não batem com a especificação — o status fica FAILED com um motivo curto. Antes de subir, valide localmente com ffprobe.

# Validar antes de submeter
ffprobe -v error -show_entries \
  stream=codec_name,width,height,duration,r_frame_rate,bit_rate \
  -of default=noprint_wrappers=1 video.mp4

# Converter pra spec ideal se precisar
ffmpeg -i input.mov \
  -c:v libx264 -preset slow -crf 22 \
  -c:a aac -b:a 192k \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -movflags +faststart \
  output.mp4

Conceitos-chave

Toda essa burocracia tem custo. Pergunta honesta: o seu volume justifica? Se você posta 2-3 vídeos por semana, o tempo investido em audit + manutenção da integração paga menos do que publicar manual no celular.

Conceitos-chave