Como publicar um vídeo no TikTok através da API
Para publicar um vídeo através da API for Business do TikTok, envie POST /business/video/publish/ com o business_id da conta, um video_url num domínio ou prefixo de URL verificado e um objeto post_info com a legenda e as definições, com o cabeçalho Access-Token. O TikTok responde com um share_id; passe-o como publish_id para /business/publish/status/ até o estado passar a PUBLISH_COMPLETE e surgirem os post_ids.
A easyCoexistence publica vídeos no TikTok com publish_tiktok_post a partir do Claude, do ChatGPT ou do seu próprio agente: indique um link HTTPS, a legenda e se os comentários ficam ativados, e depois acompanhe a publicação com get_tiktok_publish_status, enquanto o ficheiro chega ao TikTok pela sua rota de multimédia verificada.
Devolvido pela chamada de publicação, como v_pub_url~v1.2345123456789123456, e passado à chamada de estado como publish_id.
Desde então, o TikTok recusa publicar vídeos de URLs cujo domínio ou prefixo não esteja verificado.
O limite do TikTok para publicações de vídeo por conta através do endpoint de publicação, com no máximo 15 por dia.
O tempo que os post_ids podem demorar a surgir após PUBLISH_COMPLETE; o TikTok recomenda repetir a consulta ao fim de três minutos.
Enviado no webhook post.publish.publicly_available assim que uma publicação passa a moderação, pronto para consultar as suas métricas.
O que é preciso antes da primeira chamada?
Três coisas. Um token de acesso da conta do TikTok e o open_id da conta, obtidos na troca de token; uma aplicação de programador com a permissão Video Publish em TikTok Accounts; e o vídeo num URL HTTPS ou HTTP público, alojado sob um domínio ou prefixo de URL verificado para a aplicação. O TikTok transfere o ficheiro por conta própria, por isso tem de continuar acessível, e recomenda um URL que fique válido durante pelo menos 30 minutos.
Como é o pedido de publicação?
Um POST para https://business-api.tiktok.com/open_api/v1.3/business/video/publish/ com o token da conta no cabeçalho Access-Token e Content-Type definido como application/json. O corpo JSON indica a conta em business_id, o ficheiro em video_url e as definições da publicação em post_info; este exemplo publica um vídeo com legenda, mantendo ativados os comentários, o Duet e o Stitch:
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/video/publish/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"business_id": "<OPEN_ID>",
"video_url": "https://media.example.com/tiktok/launch.mp4",
"post_info": {
"caption": "Our new menu is live #food",
"is_brand_organic": false,
"is_branded_content": false,
"disable_comment": false,
"disable_duet": false,
"disable_stitch": false
}
}'Para que serve cada campo do corpo?
Os campos que a referência do TikTok indica para uma publicação de vídeo, começando pelo nível superior. A capa, o rótulo de conteúdo gerado por IA, uma localização, os rascunhos e a opção só para anúncios ficam no mesmo corpo:
business_id: oopen_idda conta, obtido na troca de token.video_url: o ficheiro que o TikTok transfere, em MP4, MOV ou WebM, num domínio ou prefixo de URL verificado.post_info: obrigatório em todas as chamadas, mesmo como objeto vazio, e onde ficam as definições da publicação.post_info.caption: até 2.200 caracteres contados em UTF-16, com #hashtags e até 30 @menções.post_info.is_brand_organiceis_branded_content: os rótulos Conteúdo promocional e Parceria paga, que a tabela do TikTok marca como obrigatórios.post_info.disable_comment,disable_duetedisable_stitch: true desativa os comentários, o Duet ou o Stitch; os três têm como predefinição false.
O que devolve o TikTok?
O envelope habitual, com o ID da tarefa de publicação em data. Um code 0 significa que o TikTok aceitou a tarefa, não que o vídeo esteja publicado: o TikTok ainda tem de transferir o ficheiro, verificá-lo e moderar a publicação. Nos exemplos do TikTok, o share_id de um vídeo começa por v_pub_url e o de uma publicação de fotos por p_pub_url.
{
"code": 0,
"message": "Ok",
"request_id": "20210817034316010245031056097316BA",
"data": {
"share_id": "v_pub_url~v1.2345123456789123456"
}
}Como acompanhar a publicação até ficar disponível?
Com GET /business/publish/status/, passando business_id e o share_id como publish_id. O status indica PROCESSING_DOWNLOAD enquanto o TikTok transfere o ficheiro, PUBLISH_COMPLETE quando a publicação passa a moderação, ou FAILED com um motivo. Os post_ids surgem com PUBLISH_COMPLETE quando a publicação está publicamente visível, e podem atrasar até três minutos. O fluxo completo em Python:
import os, time, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
HEADERS = {"Access-Token": os.environ["TIKTOK_ACCESS_TOKEN"]}
BUSINESS_ID = os.environ["TIKTOK_BUSINESS_ID"] # open_id from the token exchange
def call(method, path, **kwargs):
body = requests.request(method, f"{API}/{path}", headers=HEADERS, timeout=30, **kwargs).json()
if body.get("code") != 0: # errors arrive in code, usually with HTTP 200
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
return body["data"]
share_id = call("POST", "business/video/publish/", json={
"business_id": BUSINESS_ID,
"video_url": "https://media.example.com/tiktok/launch.mp4",
"post_info": {"caption": "Our new menu is live #food",
"is_brand_organic": False, "is_branded_content": False},
})["share_id"]
for _ in range(30):
time.sleep(60) # each check is a call; TikTok's stages take minutes
s = call("GET", "business/publish/status/",
params={"business_id": BUSINESS_ID, "publish_id": share_id})
if s["status"] == "FAILED":
raise RuntimeError(s.get("reason"))
if s["status"] == "PUBLISH_COMPLETE" and s.get("post_ids"):
print("Live:", s["post_ids"])
breakUm webhook pode substituir as verificações de estado?
Sim, para uma aplicação que subscreva o event_type VIDEO com /business/webhook/update/. O TikTok envia então post.publish.failed ou post.publish.complete quando tiver transferido e verificado o ficheiro, post.publish.publicly_available com o novo post_id assim que a moderação passar, e post.publish.no_longer_publicly_available se a publicação deixar mais tarde de estar visível ao público. Cada evento indica a tarefa em publish_id, o mesmo valor que o share_id.
Como publicar um vídeo através do MCP?
Peça-o em palavras simples ao Claude, ao ChatGPT ou a outro cliente ligado a https://easycoexistence.com/api/mcp. O assistente chama publish_tiktok_post com o account_id obtido de list_social_accounts, um video_url em HTTPS, a legenda e, se quiser os comentários desativados, disable_comment. O resultado traz o share_id do TikTok, e get_tiktok_publish_status, com o account_id e esse share_id, devolve o estado, os post_ids e o motivo tal como estão neste momento.
publish_tiktok_post {
"account_id": "<ACCOUNT_ID>",
"video_url": "https://media.example.com/tiktok/launch.mp4",
"caption": "Our new menu is live #food",
"disable_comment": false
}
=> { "share_id": "v_pub_url~v1.2345123456789123456",
"note": "TikTok is processing the post. Check it with get_tiktok_publish_status." }
get_tiktok_publish_status { "account_id": "<ACCOUNT_ID>", "share_id": "v_pub_url~v1.2345123456789123456" }
=> { "status": "PUBLISH_COMPLETE", "post_ids": ["<POST_ID>"] }O que envia o publish_tiktok_post ao TikTok?
Uma chamada ao mesmo endpoint, preenchida a partir do seu pedido. A sua ligação segue para o TikTok como uma ligação assinada através da rota de multimédia verificada da própria easyCoexistence, por isso não precisa de verificação própria; a legenda e o disable_comment seguem como os indicou; e is_brand_organic e is_branded_content seguem como false. As restantes definições, como Duet, Stitch, a capa e o rótulo de conteúdo gerado por IA, mantêm as predefinições do TikTok, e o vídeo é publicado como publicação pública, como o endpoint foi construído para fazer.
O que pode fazer com as credenciais da Partner API?
Chamar o TikTok diretamente como a conta. GET /channels/{id}?credentials=1 em https://easycoexistence.com/api/v1, com a sua chave ec_live_ como token bearer, devolve o canal com um objeto credentials: api_base, business_id, um access_token em vigor e token_expires_at. As verificações de estado, as listas de vídeos, os comentários e as métricas passam então a correr a partir do seu próprio código. A publicação é a parte a planear: uma chamada direta de publicação envia o video_url ao TikTok sem alterações, as propriedades de URL são acrescentadas com o ID e o segredo de uma aplicação de programador própria, e o prefixo que a aplicação da easyCoexistence tem verificado é a sua rota de multimédia, que o publish_tiktok_post usa.
curl "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID?credentials=1" \
-H "Authorization: Bearer $EC_API_KEY"
# "credentials": {
# "platform": "tiktok",
# "api_base": "https://business-api.tiktok.com/open_api/v1.3",
# "business_id": "<OPEN_ID>",
# "access_token": "<ACCESS_TOKEN>",
# "token_expires_at": "2026-11-01T09:00:00.000Z", ...
# }
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/publish/status/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'publish_id=<SHARE_ID>'Como configurar
- Get the token and the account IDExchange the owner's authorization code at /tt_user/oauth2/token/, and keep access_token for the header and open_id for business_id.
- Host the videoPut the MP4, MOV or WebM file under a domain or URL prefix verified for your app, where it stays reachable for at least 30 minutes.
- Call the publish endpointPOST business_id, video_url and post_info, with the caption, the two brand flags and the engagement switches, to /business/video/publish/.
- Keep the share_idStore data.share_id from the response, the ID of this publishing task.
- Check the statusEvery few minutes, GET /business/publish/status/ with business_id and the share_id as publish_id, until PUBLISH_COMPLETE or FAILED.
- Record the post IDTake it from post_ids, or from post_id in the post.publish.publicly_available webhook, to read the video's metrics later.
Erros comuns
- Deixar de fora o post_info. O TikTok exige o objeto em todas as chamadas, mesmo quando nenhuma definição muda.
- Procurar um ID de publicação na resposta de publicação. Essa resposta devolve apenas o share_id; os post_ids vêm da chamada de estado ou do webhook publicly_available.
- Repetir uma chamada de publicação que excedeu o tempo limite. O primeiro pedido pode ter chegado ao TikTok, por isso verifique as últimas publicações da conta antes de o enviar de novo.
- Tratar o code 0 como vídeo publicado. Significa que o TikTok aceitou a tarefa, e o ficheiro ainda pode falhar as verificações depois da transferência.
De US$ 9 a US$ 0,75 por ligação por mês, a descer à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Qual é o endpoint que publica um vídeo no TikTok?
POST https://business-api.tiktok.com/open_api/v1.3/business/video/publish/, com o token da conta no cabeçalho Access-Token e business_id, video_url e post_info no corpo JSON.
A API do TikTok consegue carregar diretamente um ficheiro de vídeo?
Não através de /business/video/publish/. Essa rota recebe video_url e vai buscar o ficheiro a esse endereço, por isso o vídeo precisa de um URL num domínio ou prefixo de URL verificado.
Como obtenho o ID de um vídeo publicado pela API?
A partir de post_ids em /business/publish/status/, quando o estado for PUBLISH_COMPLETE e a publicação estiver pública, ou a partir de post_id no webhook post.publish.publicly_available.
Posso agendar um vídeo do TikTok para mais tarde através da API?
O endpoint de publicação publica no momento em que é chamado e não tem campo de hora. A easyCoexistence guarda as publicações agendadas na sua própria fila e chama o TikTok à hora que definir.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em