O que o campo creator_info max_video_post_duration_sec do TikTok diz antes de você publicar

O que o campo creator_info max_video_post_duration_sec do TikTok devolve?

O campo creator_info max_video_post_duration_sec do TikTok devolve o vídeo mais longo, em segundos, que esse criador específico tem permissão de publicar. A redação do próprio TikTok não deixa espaço para uma constante global:

"The longest video duration in seconds that the TikTok creator can post. Different users have different maximum video-duration privileges. Developers should use this field to stop video posts that are too long. IGNORE if your client only sends photo media through this API."

Ele chega de um único endpoint que não recebe corpo de requisição nenhum:

O token de acesso identifica o criador, então a chamada é uma consulta de ficha e não uma busca. O TikTok descreve o propósito do endpoint no mesmo fôlego em que descreve a tela que ele deve desenhar: "When rendering the Export to TikTok page, your app must invoke the API and use the latest creator information returned to display the account's available privacy level options and video/photo interaction settings."

O que mais volta do endpoint de creator info?

Oito campos, e cada um deles existe para mudar o que a sua tela de publicação mostra:

O TTL de duas horas do avatar passa despercebido com facilidade e produz imagens quebradas em qualquer tela que guarde a URL em cache por uma sessão inteira. As duas flags disabled juntam duas causas distintas em um único booleano: uma conta privada e uma escolha explícita de "No one" devolvem true do mesmo jeito, e a resposta não dá como saber qual foi.

Por que a duração máxima de vídeo varia por criador?

Porque o TikTok concede privilégios de duração por conta e não por plataforma. O Media Transfer Guide é a única página que cita números:

"All TikTok creators can post 3-minute videos, while some have access to post 5-minute or 10-minute videos. The longest video a developer can send via the initialize Upload Video endpoint is 10 minutes. TikTok users may trim developer-sent videos inside the TikTok app to fit their accounts' actual maximum publish durations."

Isso dá um piso documentado de 180 segundos e um teto documentado de 600. A resposta de exemplo do próprio TikTok então devolve nenhum dos dois:

"max_video_post_duration_sec": 300

Trezentos segundos são a faixa do meio, cinco minutos. O exemplo é coerente com as faixas, mas nada na referência afirma que o campo se restringe a 180, 300 e 600. Ele é tipado como int32 sem enum, então um cliente que faz switch em três valores fixos está apostando numa suposição não documentada. Compare a resposta com o vídeo que você tem em mãos, nunca com uma constante.

A central de ajuda do TikTok também não fecha a lacuna. O artigo "Making a post" manda o criador "Select a maximum length for your video" e não publica número algum em lugar nenhum da página, e é por isso que a história dentro do app sobre quanto tempo pode ter um vídeo do TikTok e a história da API vivem se afastando. Para uma integração, o campo da API é o único número de fato autoritativo, e ele só é autoritativo para a conta cujo token você usou.

Quais opções de nível de privacidade voltam junto?

privacy_level_options devolve uma lista diferente conforme a conta seja pública ou privada, e o TikTok detalha as duas:

As duas listas só têm em comum MUTUAL_FOLLOW_FRIENDS e SELF_ONLY. PUBLIC_TO_EVERYONE nunca aparece para uma conta privada, e FOLLOWER_OF_CREATOR nunca aparece para uma pública. A referência de Direct Post lista os quatro valores no enum privacy_level sem essa separação, e é lendo o enum em vez da resposta que integrações acabam enviando um valor que a conta não pode usar.

A punição para isso é específica. privacy_level_option_mismatch volta no init, e o TikTok anexa um aviso a ele: "All clients are required to correctly display the creator account's privacy level options and honor the users' choice. Occurances of this error for product-use applications suggest violations to TikTok's product-use guidance."

As regras de UX são igualmente prescritivas. O TikTok exige que "Users must manually select the privacy status from a dropdown and there should be no default value", que interações desativadas fiquem em cinza e que nenhum dos controles de comentário, Duet ou Stitch comece marcado. Sobre duração, as mesmas diretrizes dizem que "API clients must check if the duration of the to-be-posted video follows the max_video_post_duration_sec returned in the creator_info API." Receber um valor de volta não é conformidade. Bloquear o post é.

Clientes não auditados recebem uma lista ainda menor. O TikTok os restringe à visibilidade SELF_ONLY e a "up to 5 users to post in a 24 hour window", com todas essas contas privadas no momento da publicação.

O que o TikTok deixa em aberto

Três lacunas merecem entrar numa checklist em vez de serem descobertas em produção.

O escopo não bate com o fluxo. Query Creator Info exige o escopo video.publish. O endpoint de upload em /v2/post/publish/inbox/video/init/ exige video.upload. Um cliente que só deixa rascunhos na caixa de entrada do criador tem, portanto, um token que não consegue chamar o endpoint cujo valor o TikTok manda respeitar. O TikTok nunca trata do conflito; a frase sobre aparar vídeos no Media Transfer Guide é o mais perto de uma solução, já que um upload de caixa de entrada longo demais chega para o criador aparar em vez de ser recusado de cara.

Uma recusa pode chegar como HTTP 200. A tabela de erros de creator info lista spam_risk_too_many_posts, spam_risk_user_banned_from_posting e reached_active_user_cap sob o status HTTP "200 (intentional)". Um cliente que só ramifica por código de status lê isso como sucesso e mostra uma tela de publicação que não publica. A orientação do TikTok é parar: "When the creator_info API returns that the creator can not make more posts at this moment, API Clients must stop the current publishing attempt and prompt users to try again later."

O teto de posts é descrito, não publicado. O TikTok escreve que "There is a limit on the number of posts that can be made to a creator account in a 24-hour window via Direct Post API. The upper limit may vary among creators (typically around 15 posts per day/ creator account) and is shared across all API Clients using Direct Post." Nenhum campo devolve esse número, e "typically around" é o máximo de precisão que o TikTok oferece, uma declaração bem mais mole que a cifra seca por trás do limite de publicação de conteúdo do Instagram.

Não existe mínimo documentado. A referência da API publica uma duração máxima por criador e nada sobre o piso. Um vídeo curto demais só aparece depois do fato, como o motivo de falha duration_check_failed de /v2/post/publish/status/fetch/, descrito como "Video does not meet our duration restrictions."

Trate a chamada de creator info como parte de toda publicação, não parte do onboarding. As opções de privacidade, as flags de interação e o limite de duração mudam quando o criador mexe numa configuração, que é exatamente por que qualquer ferramenta que agenda posts no TikTok precisa consultar de novo na hora de publicar em vez de reaproveitar o que guardou semana passada. A legenda que você anexa é regida à parte, pelo teto de 2200 runas UTF-16 tratado no limite de caracteres da legenda do TikTok.

Perguntas frequentes

O max_video_post_duration_sec devolve algo além de 180, 300 ou 600?

O TikTok não promete esses três valores. O campo é um int32, a referência não publica enum e só o Media Transfer Guide menciona privilégios de 3, 5 e 10 minutos. Compare o seu vídeo com o número devolvido, não com um conjunto fixo no código.

O que acontece se eu publicar um vídeo mais longo que o limite devolvido?

Por Direct Post o trabalho falha com o motivo duration_check_failed. Pelo endpoint de upload o TikTok afirma que "TikTok users may trim developer-sent videos inside the TikTok app to fit their accounts' actual maximum publish durations", ou seja, o criador resolve isso durante a edição.

Uma integração só de fotos pode ignorar esse campo?

Pode, e o TikTok diz isso diretamente. max_video_post_duration_sec, duet_disabled e stitch_disabled estão todos marcados com "IGNORE if your client only sends photo media through this API."

Com que frequência posso chamar o endpoint de creator info?

Vinte vezes por minuto por token de acesso de usuário. É o teto publicado mais alto entre os endpoints de publicação, que ficam em 6 requisições por minuto para chamadas de init e 30 para a consulta de status.

Por que duet_disabled está true se o criador nunca desligou o Duet?

Porque uma conta privada liga a mesma flag. O TikTok devolve true se "the creator account is private or they set the Duet interaction to "No one" in their privacy setting", e a resposta não dá como distinguir as duas causas.

O endpoint informa se a conta é pública ou privada?

Não como campo, mas privacy_level_options entrega. Uma lista com PUBLIC_TO_EVERYONE pertence a uma conta pública, e uma com FOLLOWER_OF_CREATOR pertence a uma privada, já que os dois valores nunca aparecem juntos.

Preciso consultar o creator info antes de cada post ou basta uma vez na integração?

Antes de cada post, não só na integração. As opções de privacidade, os sinalizadores de interação e o limite de duração mudam assim que o criador ajusta uma configuração, então um valor obtido na semana passada já pode estar desatualizado. Ferramentas que agendam posts no TikTok precisam consultar de novo no momento da publicação, em vez de reaproveitar uma resposta guardada.

O que acontece se meu app deixar o criador escolher um nível de privacidade fora de privacy_level_options?

O TikTok devolve o erro privacy_level_option_mismatch no init. Para aplicações de product-use, o TikTok trata ocorrências repetidas desse erro como indício de violação das suas diretrizes, já que os clientes devem exibir apenas as opções de privacidade que a conta realmente tem.

Quais restrições extras valem para um app do TikTok que ainda não passou pela auditoria?

O TikTok restringe clientes não auditados ao nível de privacidade SELF_ONLY e a postar para até 5 usuários em uma janela de 24 horas. Cada uma dessas contas precisa estar privada no momento da postagem.

O TikTok publica um número exato para o teto diário de posts por conta de criador?

O TikTok não publica nenhum número exato. Ele descreve um limite compartilhado entre todos os clientes de API que é "normalmente em torno de 15 posts por dia/conta de criador" e pode variar por criador, sem que nenhum campo de resposta devolva esse número.