Por que a verificação de domínio do pull_from_url da API do TikTok recusa o seu host

O que é a verificação de domínio do pull_from_url da API do TikTok?

Passar na verificação de domínio do pull_from_url da API do TikTok significa que o TikTok confirmou que você controla o host que serve o seu arquivo de mídia, e enquanto essa confirmação não existir nenhum arquivo é buscado. É uma checagem de posse sobre a URL, não sobre o vídeo, e acontece antes de o downloader do TikTok abrir uma única conexão.

A checagem vale para toda chamada de init que carrega source: "PULL_FROM_URL":

Fotos não têm alternativa. O endpoint de fotos afirma que "Only PULL_FROM_URL is allowed" em source_info.source, ou seja, a verificação não é uma otimização para postar fotos, é o pré-requisito inteiro. Vídeos conseguem escapar trocando para FILE_UPLOAD, embora as Content Sharing Guidelines do TikTok empurrem para o outro lado: "If video resources are already on API Clients' servers, do not use FILE_UPLOAD; use PULL_FROM_URL instead."

Como verificar um domínio no TikTok?

Você adiciona o host como propriedade do seu app e depois comprova o controle por DNS. O Media Transfer Guide do TikTok descreve o fluxo em uma frase:

"To confirm ownership, log into the TikTok for Developers website and add your Domain or URL Prefix property to your application in the URL properties widget as shown below. You must have manage or write access to the property."

Sobre o método em si, o TikTok escreve: "To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records." A palavra "recommended" sugere que existe um segundo caminho, e o TikTok não documenta nenhum. Não há método publicado com meta tag em HTML, não há método por upload de arquivo, nenhum tipo de registro é nomeado, não há orientação de TTL e nenhuma indicação de quanto tempo a propagação pode levar ou se o TikTok checa o registro de novo mais tarde. Se o seu DNS está delegado a um provedor que você não controla, é essa lacuna não documentada que trava você, e a documentação não oferece plano B.

O mecanismo é o mesmo que sustenta um handle de domínio próprio no Bluesky: uma string num registro de DNS prova que quem pediu a verificação também administra a zona.

Até onde chega um domínio verificado?

Para baixo, nunca para cima. O TikTok enuncia a regra e em seguida dá o exemplo que a torna concreta:

"Once the ownership of a domain is verified, all paths under that domain or its subdomains are considered owned by the developer application."

"For example, if you have verified the domain static.example.com, then URLs like https://video.static.example.com/tiktok/example.mp4 are considered verified, while URLs like https://example.com/videos/example.mp4 are still considered unverified."

Leia essa segunda metade de novo, porque é a armadilha. Verificar um subdomínio não verifica o domínio pai. Um time que verifica cdn.example.com e depois move os arquivos para example.com/cdn/ perde a verificação por completo, mesmo que a organização obviamente continue dona dos dois. O domínio apex é uma propriedade separada e precisa do próprio registro.

Propriedades do tipo URL Prefix são ainda mais estreitas, e o TikTok define o formato com precisão: "A URL prefix consists of: https:// + host + path + /." O host "must be a domain and should not be an IP address", e a comparação é literal:

"For example, if you have already verified the domain https://example.com/videos/user/, then URLs like https://example.com/videos/user/123/example.mp4 are considered verified, while URLs like https://example.com/videos/2023/user/123/example.mp4 are still considered unverified."

Repare que o TikTok chama um prefixo de URL de "the domain" no próprio exemplo de prefixo. A redação é frouxa, o comportamento não é: inserir 2023/ entre videos/ e user/ produz uma string que já não começa pelo prefixo verificado, e a requisição falha. Qualquer layout de armazenamento que coloque uma data, um ID de tenant ou um número de shard antes do trecho verificado vai falhar do mesmo jeito, o que é um bom argumento para verificar o domínio em vez de um caminho profundo.

Quais são as outras regras do pull_from_url?

Três condições acompanham a posse, e o TikTok enuncia cada uma sem rodeios.

O esquema é fixo: "The media URL must use "https" and should not redirect to another URL." As regras de prefixo são mais duras sobre o que acontece se houver redirecionamento: "Redirections are not followed. URLs that return HTTP 3xx are considered invalid." Um serviço de URL assinada que responde com um 302 para o armazenamento, ou um CDN que desvia a requisição um salto, é invisível num teste de navegador e fatal aqui. Esse é um dos poucos lugares em que uma cadeia de redirecionamentos não é uma nota de rodapé de performance e sim uma falha completa.

A URL tem que continuar viva pelo trabalho inteiro: "The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated." URLs assinadas de vida curta precisam de validade maior que uma hora, não maior que alguns minutos.

A banda tem um teto declarado: "TikTok server's ingress bandwidth for file downloads can reach 100 Mbps." O TikTok não publica mínimo algum, então uma origem com limite de taxa simplesmente queima o relógio até o timeout de uma hora encerrar a tarefa.

O TikTok também publica uma saída de emergência para testes. O Media Transfer Guide traz o link de um MP4 de exemplo no próprio CDN e observa que você pode usá-lo "without any verification", o que permite exercitar todo o fluxo de init e status antes de o seu registro de DNS existir.

Como é o erro url_ownership_unverified?

Um host não verificado devolve HTTP 403 com error.code igual a url_ownership_unverified. O curioso é que o TikTok descreve esse mesmo código de três jeitos diferentes em três páginas no ar:

"Video transfer method", "content transfer method" e "media transfer method" são o mesmo mecanismo com três nomes. Case pela string do código, nunca pela mensagem. A terceira linha é mais estranha que a redação: url_ownership_unverified aparece na especificação de resposta documentada de /v2/post/publish/cancel/, um endpoint que recebe apenas um publish_id e nenhuma URL. O TikTok não explica como uma requisição de cancelamento pode falhar numa checagem de posse, e a lista de campos não lhe dá meio de fazer isso.

Passar na verificação não é o mesmo que o download dar certo. Depois que a posse é aceita, as falhas descem para o fail_reason devolvido por /v2/post/publish/status/fetch/, onde video_pull_failed e photo_pull_failed dividem uma única descrição: "The TikTok server encountered a connection error while downloading the specified video resource, or the download is terminated since it can not be completed within the one-hour timeout." Problemas de formato e de tamanho chegam à parte, como file_format_check_failed ou picture_size_check_failed, no mesmo espírito dos requisitos de imagem do Instagram que recusam um arquivo que subiu sem nenhum problema.

Vale configurar um campo na mesma requisição. is_aigc marca mídia sintética no momento da publicação, e os dois sabores do rótulo de conteúdo gerado por IA do TikTok se comportam de formas bem diferentes conforme você defina o campo ou o TikTok deduza sozinho.

Perguntas frequentes

Verificar example.com também verifica cdn.example.com?

Sim. O TikTok afirma que "all paths under that domain or its subdomains are considered owned by the developer application", então um apex verificado cobre os subdomínios. O contrário falha: verificar cdn.example.com deixa example.com sem verificação.

Posso usar um endereço IP ou uma URL http simples?

Não nos dois casos. O TikTok exige que "The media URL must use "https"", e a definição de prefixo de URL afirma que o host "must be a domain and should not be an IP address."

Por que minha URL assinada do S3 ou do Cloud Storage falha na verificação?

Normalmente porque o host do bucket não é uma propriedade do seu app ou porque a URL assinada responde com um redirecionamento. O TikTok não segue redirecionamentos e trata qualquer resposta HTTP 3xx como inválida, então o salto até o backend de armazenamento encerra a tentativa.

Quantas URLs de foto uma requisição pode levar?

Até 35. O endpoint de fotos descreve photo_images como "An array containing up to 35 photo content URLs. The URLs must be publicly accessible and verified by your app", e cada uma dessas URLs passa pela mesma checagem de posse.

A janela de uma hora começa no init ou no primeiro byte?

No início da tarefa. O TikTok diz que o download "times out one hour after the download task is initiated", então uma origem lenta queima o mesmo relógio que um arquivo grande, e a tarefa termina em video_pull_failed em vez de esperar.

Dá para cancelar um download que já está rodando?

Só na base do melhor esforço. /v2/post/publish/cancel/ recebe o publish_id, e o TikTok avisa que "it is not feasible to cancel downloads that are nearing completion or already in the file processing state." Um cancelamento bem-sucedido aparece depois como o motivo de falha publish_cancelled.

Dá para pular totalmente a verificação de domínio do TikTok?

Só se você estiver publicando vídeo. Trocar o método de transferência para FILE_UPLOAD remove a checagem de propriedade, mesmo que as Content Sharing Guidelines do TikTok recomendem o contrário para um vídeo que já está no seu servidor. Para fotos essa opção não existe: o endpoint de fotos só permite PULL_FROM_URL, então ali a verificação é obrigatória.

Dá para testar o PULL_FROM_URL antes de o meu registro DNS existir?

O TikTok publica exatamente uma exceção para isso. O Media Transfer Guide linka um MP4 de exemplo hospedado no próprio CDN dele e diz que funciona "sem nenhuma verificação", então dá para rodar todo o fluxo de init e status antes de adicionar um registro DNS. Isso cobre só esse arquivo específico, não os seus próprios arquivos de mídia.

Com que velocidade o TikTok baixa o arquivo da minha URL?

Até o teto informado pelo TikTok, 100 Mbps de largura de banda de entrada para downloads de arquivos. O TikTok não publica um mínimo para a sua origem, então um servidor com banda limitada só deixa o relógio da janela de uma hora correr até a tarefa terminar em video_pull_failed ou photo_pull_failed.

Qual é a diferença entre url_ownership_unverified e video_pull_failed?

url_ownership_unverified é a checagem prévia: o TikTok rejeita a chamada init com HTTP 403 antes mesmo de abrir uma conexão com a sua URL. video_pull_failed, e seu equivalente para fotos, photo_pull_failed, acontece depois, já com a checagem de propriedade aprovada, quando o próprio download sofre um erro de conexão ou ultrapassa o limite de uma hora.