Por que o limite de caracteres da legenda do TikTok é medido em runas UTF-16

Qual é o limite de caracteres da legenda do TikTok?

Na documentação, o limite de caracteres da legenda do TikTok é de 2200 runas UTF-16 para a legenda de um vídeo e 90 runas UTF-16 para o título de um post de fotos, mais um campo de descrição separado de 4000 runas que só os posts de fotos têm. Os três números vêm da referência da Content Posting API do TikTok, e os três são indicados em runas e não em caracteres. Tudo o que vem abaixo descreve a API, porque é o único lugar onde o TikTok publica um número.

A palavra "caption" não é nome de campo em lugar nenhum da API. Em um vídeo, a legenda vai em title. Em um post de fotos, title é um título curto e o texto da legenda pertence a description. Mesmo aplicativo, mesma pessoa, mesmo ato de escrever uma legenda, dois nomes de campo cujos limites estão separados por um fator de vinte e quatro.

A terceira linha pega muita gente de surpresa. O endpoint de upload que deposita um vídeo na caixa de entrada do TikTok do criador não aceita texto nenhum. O corpo da requisição contém source, video_size, chunk_size, total_chunk_count e video_url, e nada mais. O TikTok avisa quem integra: "You should inform users that they must click on inbox notifications to continue the editing flow in TikTok and complete the post." Se o seu agendador publica por esse endpoint, a legenda nunca sai do seu banco de dados.

O que é uma runa UTF-16?

O TikTok não diz. A expressão "UTF-16 runes" aparece nas descrições dos campos sem definição, sem link e sem exemplo, e solda duas unidades de duas tradições diferentes. Uma runa é o nome que o Go dá a um ponto de código Unicode. UTF-16 é uma codificação cuja unidade de medida é a unidade de código, e caracteres astrais ocupam duas. Então "UTF-16 rune" se lê como "code point" ou como "UTF-16 code unit", e esses são números diferentes.

São o mesmo número para inglês simples. Divergem em qualquer coisa acima de U+FFFF, que é onde moram todos os emojis pictográficos.

Escritas não latinas não são o problema que se imagina. Os kana japoneses ficam no Plano Multilíngue Básico, então cinco kana custam cinco nas duas leituras. O que custa o dobro é tudo o que está codificado acima de U+FFFF: emojis, escritas históricas, alguns blocos de extensão CJK, alfanuméricos matemáticos.

Eu leio a ambiguidade como um aceno para unidades de código, porque esse é o número que um servidor recebe de graça: String.prototype.length em JavaScript e String.length() em Java devolvem unidades de código. Isso é um palpite sobre a implementação do TikTok, não algo que o TikTok afirme, então trate 2200 e 90 como tetos sob os quais você fica, e não como alvos que você acerta.

Quanto um emoji custa do limite?

Entre 1 e 11, e quem lê vê um único glifo nos dois casos. O custo é o número de pontos de código do emoji em uma leitura, e a soma das larguras UTF-16 deles na outra. Todo ponto de código acima de U+FFFF tem 2 unidades de código de largura. Zero width joiners e seletores de variação valem 1 cada.

O portal torii é o caso estranho. É um símbolo do BMP carregando um seletor de variação, então as duas leituras concordam em 2 enquanto quem lê vê 1. O emoji de família é o caro, com 11 unidades de código, o que em um título de foto de 90 runas é mais de um décimo do campo.

Um título de foto que passa em uma leitura e falha na outra

Pegue este título de post de fotos: Autumn in Kyoto: the twelve quiet corners we walked before dawn, day 1 🍁🍂🏯🌄👘🎋⛩️👩‍👩‍👧‍👦. São 71 caracteres ASCII e oito emojis. Uma pessoa lendo conta 79 coisas, confortavelmente dentro de 90.

Leia "UTF-16 runes" como pontos de código e o título tem 86, que cabe. Leia como unidades de código UTF-16 e ele tem 96, que não cabe. Uma string, um limite documentado de 90, duas leituras defensáveis, respostas opostas. Troque o emoji de família por 👪 U+1F46A e o mesmo título cai para 87 na leitura estrita e publica nas duas.

Por que a mesma legenda quebra em um post de fotos?

Porque a legenda de um vídeo tem 2200 runas para gastar e o título de uma foto tem 90. Uma ferramenta que guarda uma legenda por post agendado e a mapeia para title nos dois endpoints fica bem no vídeo e 24 vezes acima do orçamento na foto. Ou ela corta a string antes de enviar, jogando fora a maior parte da legenda sem aviso, ou o TikTok rejeita a chamada.

Se o TikTok rejeita, a resposta não é específica. Nenhuma das duas referências publica um erro nomeado para uma legenda longa demais. O curinga é invalid_param em HTTP 400, descrito como "Check error message for details", e o resto dos códigos documentados cobre outros terrenos: spam_risk_too_many_posts, reached_active_user_cap, url_ownership_unverified, privacy_level_option_mismatch, scope_not_authorized, rate_limit_exceeded. A validação de tamanho tem que acontecer no seu código, porque a API não vai dizer qual campo estava longo demais.

O mapeamento certo trata posts de fotos como dois campos e não como um. Deixe o título curto em title e coloque o corpo da legenda em description, que com 4000 runas é o campo de texto mais folgado de toda a Content Posting API. O campo chamado description em um post de fotos comporta quase o dobro do que o campo chamado title comporta em um vídeo. Os nomes estão trocados em relação aos tamanhos.

Hashtags são uma segunda assimetria. O TikTok documenta a análise só para o campo do vídeo, em uma frase que sai com um erro de digitação: "Hashtags (#) and mentions (@) will be matched, or deliminated by spaces or new lines." Nenhuma frase equivalente aparece na referência de fotos, para nenhum dos dois campos. Se uma #tag digitada em uma descrição de foto vira uma tag de verdade é algo não documentado, então teste antes em um post SELF_ONLY.

Como contar uma legenda do TikTok antes de enviar?

Calcule os três números e valide contra o maior. Intl.Segmenter te dá a contagem de quem lê no Node e no navegador sem dependência, e os outros dois já vêm prontos.

const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
 
const readings = (text) => ({
  reader: [...segmenter.segment(text)].length,
  codePoints: [...text].length,
  utf16Units: text.length,
});
 
const LIMITS = { videoTitle: 2200, photoTitle: 90, photoDescription: 4000 };
 
const fits = (text, field) => readings(text).utf16Units <= LIMITS[field];

text.length é a leitura estrita, então validar contra ele te mantém seguro nas duas interpretações. Não recorra a Buffer.byteLength(text, 'utf8') aqui. Bytes UTF-8 são uma terceira unidade, que cobra 3 por kana e 4 por emoji astral, e nada na documentação do TikTok pede isso. Essa regra é do Threads. Confundir as duas rejeita legendas que o TikTok teria aceitado.

O limite da legenda dentro do app é o mesmo da API?

O TikTok não publica um número para dentro do app, então não há o que comparar. A referência da Content Posting API informa 2200, 90 e 4000 para os três campos da API e não diz nada sobre o editor dentro do app. Os artigos da central de ajuda que cobririam isso ficam em URLs que eu não consegui alcançar. Os números que circulam sobre o editor do app remontam a posts de marketing e não ao TikTok, então eu não vou repeti-los.

Trate os dois como coisas separadas até o TikTok documentar o contrário. Uma legenda digitada no app e uma legenda enviada por /v2/post/publish/video/init/ percorrem caminhos diferentes, e só um deles tem um número publicado.

Mais uma restrição está documentada, em outra página. As diretrizes de compartilhamento de conteúdo do TikTok exigem que "API Clients must allow users to enter or select the following metadata for a post: a. Title", e que "Preset text, including any text in the title field or hashtags, should be allowed to be edited by the user before posting content." Uma ferramenta que gera uma legenda e publica sem chance de edição está fora de conformidade, por mais runas que tenha usado.

Onde o adaptlypost entra

O adaptlypost publica no TikTok pela mesma Content Posting API, então 2200, 90 e 4000 valem para um post agendado exatamente como valem para um digitado na hora. Os limites da plataforma são do TikTok. O que o agendamento muda é quando você descobre esses limites, porque uma legenda escrita em um calendário de conteúdo pode ser medida dias antes do horário de envio, em vez de no instante em que a API devolve invalid_param.

O descompasso fica mais nítido assim que um rascunho vai para várias redes, que é o caso comum na publicação multiplataforma. Cada rede define a própria unidade de contagem, então uma legenda dimensionada para uma não é automaticamente segura na próxima. Se você escreve com o gerador de legendas com IA, o hábito útil é deixar os emojis no fim, onde cortá-los não custa nada.

Para agendamento, veja o agendador de posts do TikTok. Para os endpoints, veja a API de publicação do TikTok, e para saber o que os posts fizeram depois, o analytics do TikTok.

Perguntas frequentes

Qual é o tamanho máximo de uma legenda do TikTok na API?

2200 runas UTF-16 para a legenda de um vídeo, que a referência da Content Posting API do TikTok coloca no campo title de /v2/post/publish/video/init/. Posts de fotos são diferentes: title tem teto de 90 runas UTF-16 e description de 4000, os dois em /v2/post/publish/content/init/.

O que o TikTok quer dizer com runas UTF-16?

O TikTok não define o termo. Uma runa é a palavra do Go para um ponto de código Unicode, enquanto UTF-16 mede em unidades de código, e as duas leituras diferem para todo caractere acima de U+FFFF. Valide contra a contagem de unidades de código, que é text.length em JavaScript, porque é a maior das duas e te mantém dentro do limite em qualquer leitura.

Por que o limite da legenda de foto no TikTok é de só 90 caracteres?

O teto de 90 runas é do title, que em posts de fotos é um campo de título e não a legenda. O corpo da legenda pertence a description, que permite 4000 runas UTF-16. Uma ferramenta que mapeia uma única legenda guardada para title nos endpoints de vídeo e de foto bate nos 90 e não tem o que fazer além de truncar.

Quantos caracteres um emoji usa em uma legenda do TikTok?

Entre 1 e 11, dependendo de como ele é montado. Um emoji de ponto de código único como 😀 custa 1 como ponto de código e 2 como unidades de código UTF-16. O emoji de família de quatro pessoas 👩‍👩‍👧‍👦 são sete pontos de código soldados por zero width joiners, ou seja 7 ou 11 conforme a leitura, para algo que quem lê enxerga como um glifo só.

Que erro o TikTok devolve quando uma legenda é longa demais?

O TikTok não publica nenhum erro nomeado para legenda longa demais. O curinga é invalid_param em HTTP 400, documentado como "Check error message for details", e os outros códigos publicados cobrem risco de spam, cotas, propriedade de URL não verificada, divergência de privacidade e autorização. Confira o tamanho por conta própria antes de chamar o endpoint.

O limite da legenda do TikTok dentro do app é o mesmo da API?

O TikTok não publica um número para o editor dentro do app, então os dois não podem ser comparados a partir da documentação. Os valores 2200, 90 e 4000 são declarados apenas para campos da API, na referência da Content Posting API. Qualquer número sobre o app que você encontrar em outro lugar não vem do TikTok.

Dá para adicionar uma legenda ao postar um vídeo do TikTok nos rascunhos?

O endpoint que envia um vídeo para a caixa de entrada do criador no TikTok, /v2/post/publish/inbox/video/init/, não tem nenhum campo de texto. O corpo da requisição só aceita source, video_size, chunk_size, total_chunk_count e video_url. O TikTok espera que o criador adicione a legenda dentro do app depois de tocar na notificação da caixa de entrada, porque uma legenda enviada pelo seu agendador nunca chega a esse endpoint.

O TikTok interpreta hashtags num post de fotos do mesmo jeito que num vídeo?

O TikTok documenta a leitura de hashtags e menções só para o campo title do vídeo, numa frase que as descreve como "matched, or deliminated by spaces or new lines". A referência de fotos não traz uma frase equivalente, nem para title nem para description. Se uma #tag digitada numa legenda de foto vira uma tag de verdade não está documentado, então teste primeiro num post SELF_ONLY.

Uma ferramenta de agendamento pode publicar uma legenda do TikTok sem deixar você editar antes?

As diretrizes de compartilhamento de conteúdo do TikTok proíbem isso. Elas exigem que os clientes da API deixem o usuário digitar ou escolher um título, e que o texto pré-definido no campo de título ou nas hashtags possa ser editado antes de publicar. Uma ferramenta que gera uma legenda e publica sem chance de edição fica fora de conformidade, não importa quantas runas usou.

Você deve contar uma legenda do TikTok em bytes UTF-8?

Bytes UTF-8 são a unidade errada para o TikTok. Os limites documentados pelo TikTok estão em runas UTF-16, não em bytes, e o UTF-8 cobra 3 bytes por caractere kana e 4 por emoji acima do plano básico, números que a documentação do TikTok nunca pede. Essa regra de bytes é do Threads; misturar as duas rejeita legendas que o TikTok teria aceitado.