Como o chunk_size da API do TikTok e o total_chunk_count fecham a conta

O que o campo chunk_size da API do TikTok faz?

O campo chunk_size da API do TikTok diz aos servidores do TikTok quantos bytes cada requisição PUT vai carregar quando você transfere um vídeo com source: "FILE_UPLOAD". Você o declara uma vez, no corpo da chamada de init, antes de um único byte de vídeo se mover. Tudo o que o TikTok valida depois é conferido contra essa declaração.

Três campos viajam juntos dentro de source_info, e o TikTok os descreve assim:

Campo	Tipo	Descrição do TikTok
video_size	int64	"The size of the video to be uploaded in bytes."
chunk_size	int64	"The size of the chunk in bytes."
total_chunk_count	int64	"The total number of chunks."

Os dois endpoints de init os aceitam. O /v2/post/publish/inbox/video/init/ é o endpoint de Upload, que deixa um rascunho na caixa de entrada do criador. O /v2/post/publish/video/init/ é o endpoint de Direct Post, que publica direto no perfil. A referência de Upload marca os três campos como "true for FILE_UPLOAD". A referência de Direct Post marca o video_size como "true for FILE_UPLOAD" e deixa a coluna de obrigatoriedade vazia para chunk_size e total_chunk_count. O TikTok nunca afirma que os dois campos são opcionais no Direct Post, e as regras de chunk que ele publica estão escritas uma vez só para os dois endpoints, então trate as células vazias como um artefato de formatação e envie os três.

Qual é o tamanho mínimo e máximo de chunk no TikTok?

Cada chunk precisa ter ao menos 5 MB e no máximo 64 MB, com uma exceção no fim do arquivo. O Media Transfer Guide do TikTok enuncia assim:

"Each chunk must be at least 5 MB but no greater than 64 MB, except for the final chunk, which can be greater than chunk_size (up to 128 MB) to accommodate any trailing bytes."

Mais três frases na mesma lista fecham o conjunto de regras:

Regra	Redação do TikTok
Arquivos pequenos	"Videos with a total size less than 5 MB must be uploaded as a whole, with chunk_size equal to the entire video's byte size."
Arquivos grandes	"Videos with a total size greater than 64 MB must be uploaded in multiple chunks."
Contagem de chunks	"There must be a minimum of 1 chunk and a maximum of 1000 chunks."
Ordenação	"File chunks must be uploaded sequentially."

A regra de ordenação é a que as pessoas descobrem tarde. Chunks não podem ser distribuídos entre workers, porque o TikTok rastreia um único offset de bytes por tarefa de upload e responde 416 RequestedRangeNotSatisfiable quando um cabeçalho Content-Range chega fora de ordem.

Como o total_chunk_count é calculado?

Divida e arredonde para baixo, nunca para cima. A frase exata do TikTok:

"The value of total_chunk_count should be equal to video_size divided by chunk_size, rounded down to the nearest integer."

O exemplo trabalhado do TikTok é um arquivo de 50,000,123 bytes com um chunk_size de 10,000,000. Cinquenta milhões divididos por dez milhões dá cinco vírgula zero zero zero zero um dois três, então o total_chunk_count é 5, e não 6. Os 123 bytes que sobram não ganham requisição própria. Eles pegam carona no quinto chunk, que fica com 10,000,123 bytes, um pouco maior que o chunk_size declarado:

Requisição	Content-Range	Bytes neste chunk	Status
1	bytes 0-9999999/50000123	10,000,000	206
2	bytes 10000000-19999999/50000123	10,000,000	206
3	bytes 20000000-29999999/50000123	10,000,000	206
4	bytes 30000000-39999999/50000123	10,000,000	206
5	bytes 40000000-50000122/50000123	10,000,123	201

É aqui que uma função de teto quebra uma integração em silêncio. Arredondar para cima dá um sexto chunk de 123 bytes, que é ao mesmo tempo um chunk que o TikTok não espera e um chunk muito abaixo do piso de 5 MB. A mesma lógica explica por que o TikTok permite um chunk final de até 128 MB: com um chunk_size de 64 MB, os bytes que sobram se fundem ao último chunk cheio e podem empurrá-lo para perto do dobro do tamanho declarado.

O caso do upload inteiro é a versão degenerada da mesma fórmula. Um arquivo de 4,194,304 bytes com chunk_size 4,194,304 divide exatamente em 1, então o total_chunk_count é 1 e o único PUT devolve 201 Created em vez de 206.

Arredondar para baixo ou para cima

Arredondar para baixo (a regra do TikTok)

• total_chunk_count = 5
• O chunk 5 carrega os 123 bytes finais, 10,000,123 bytes no total
• O PUT final retorna 201 Created

Arredondar para cima (o bug)

• total_chunk_count = 6
• O chunk 6 tem 123 bytes, uma requisição que o TikTok não espera
• 123 bytes ficam bem abaixo do piso de 5 MB

Onde as próprias regras de chunk do TikTok se contradizem?

Três lacunas ficam na mesma página de documentação, e cada uma custa uma sessão de depuração.

O piso contradiz o exemplo. O TikTok escreve que "each chunk must be at least 5 MB" e depois publica um exemplo de upload inteiro em que o único chunk tem 4,194,304 bytes, ou seja, 4 MB. A exceção é real, já que vídeos abaixo de 5 MB "must be uploaded as a whole", mas o piso está escrito como algo absoluto poucas linhas acima do exemplo que o viola. A leitura que funciona: o piso de 5 MB vale para todo chunk de um upload de múltiplos chunks, e um upload de chunk único está isento.

MB nunca é definido. O TikTok usa MB para o piso, o teto e a permissão do chunk final sem dizer se significa 1,000,000 ou 1,048,576 bytes. Os dois exemplos dele também não concordam. O exemplo em chunks usa um chunk decimal de 10,000,000 bytes; o exemplo de upload inteiro usa um arquivo binário de 4,194,304 bytes. Um chunk de 5,000,000 bytes é 5 MB pela leitura decimal e 4.77 MiB pela binária. O TikTok não publica resposta, então a jogada segura é passar das duas barras de uma vez e nunca mandar um chunk não final abaixo de 5,242,880 bytes.

O teto de 1000 chunks nunca pode ser alcançado. O TikTok limita arquivos de vídeo a "Maximum of 4GB" e limita a contagem de chunks a 1000, enquanto põe o piso do chunk em 5 MB. Um arquivo de 4 GB partido em chunks de 5 MB dá 800 requisições pela leitura decimal e 819 pela binária. Os dois ficam bem abaixo de 1000, então o teto de contagem de chunks é peso morto a menos que o TikTok suba o limite de tamanho de arquivo. O limite que realmente aperta o seu loop é o tempo de vida de uma hora do upload_url, exatamente como acontece com o protocolo de upload retomável do Instagram.

Que erros voltam quando a aritmética do chunk está errada?

O TikTok não publica nenhum código de erro dedicado para a matemática dos chunks. A chamada de init responde 400 com o código de erro invalid_param e a descrição "Check error message for details.", o que empurra o diagnóstico para o campo de texto livre message e para o log_id. Tudo mais específico acontece na hora da transferência, no PUT para o upload_url:

Código HTTP	Status	Descrição do TikTok
201	Created	"All parts are uploaded. TikTok will start the posting process."
206	PartialContent	"The current chunk has been successfully processed. There are additional chunks yet to be uploaded."
400	BadRequest	"Malformated request headers, or BYTE_SIZE_OF_THIS_CHUNK does not reflect the true byte size of the binary in the request body."
403	Forbidden	"The upload_url has expired."
404	NotFound	"TikTok cannot find a valid upload task given the upload_url."
416	RequestedRangeNotSatisfiable	"Content-Range does not reflect the actual upload progress."
5xx	InternalServerError	"Gateway connection error or TikTok Internal error. You should retry submitting this chunk."

Leia esses dois erros de cliente com atenção, porque eles se separam bem. Um 400 quer dizer que os bytes no corpo não batem com o que o Content-Length afirma sobre este chunk. Um 416 quer dizer que o chunk é o chunk errado: os offsets em Content-Range não são onde o cursor do TikTok está agora. Aritmética errada de total_chunk_count quase sempre aparece como 416 na requisição seguinte à que deveria ter sido a última.

Recuperar não exige recomeçar o arquivo. O TikTok devolve o cursor de progresso em todo cabeçalho de resposta como Content-Range: bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH}, e /v2/post/publish/status/fetch/ devolve o mesmo número como uploaded_bytes. Retome daquele offset enquanto o upload_url ainda estiver dentro da janela de uma hora, e então consulte até o PUBLISH_COMPLETE.

Três limites cercam o exercício inteiro e vale conferi-los antes de calcular um único chunk. Vídeos param em 4 GB e 10 minutos pela API, o que importa mais do que parece dado o quanto o teto de duração de vídeo do TikTok no app já se moveu. Legendas param em 2200 runas UTF-16 em post_info.title, o mesmo número coberto no limite de caracteres de legenda do TikTok. E o PULL_FROM_URL pula toda essa dança de chunks, que é o motivo de o TikTok dizer aos desenvolvedores que arquivos no servidor nunca deveriam usar FILE_UPLOAD.

Perguntas frequentes

O chunk_size precisa ser idêntico em todos os chunks?

Sim para todos menos o último. As regras de chunk do TikTok deixam só o chunk final passar do chunk_size que você declarou no init, "up to 128 MB", para absorver bytes que sobram e não dividem por igual.

O que acontece se o total_chunk_count for um a mais do que o TikTok espera?

O upload falha na requisição extra, não no init. O TikTok já recebeu o TOTAL_BYTE_LENGTH inteiro a essa altura, então o PUT excedente chega com offsets além do fim do arquivo e devolve 416 RequestedRangeNotSatisfiable com a descrição "Content-Range does not reflect the actual upload progress."

O mínimo de 5 MB do TikTok é 5,000,000 ou 5,242,880 bytes?

O TikTok não diz. O Media Transfer Guide escreve "5 MB" sem nenhum número em bytes, e seus dois exemplos usam tamanhos decimal e binário respectivamente. Enviar ao menos 5,242,880 bytes por chunk não final satisfaz qualquer uma das interpretações.

Os chunks podem ser enviados em paralelo?

Não. O TikTok afirma que "File chunks must be uploaded sequentially", e o servidor rastreia um offset de upload por tarefa, então um chunk que chega antes do seu antecessor é rejeitado com 416 em vez de ser guardado em buffer.

O PULL_FROM_URL precisa de chunk_size e total_chunk_count?

Não. Esses três campos são marcados como "true for FILE_UPLOAD" apenas. Com source: "PULL_FROM_URL" você envia video_url no lugar, o TikTok baixa o arquivo sozinho, e a resposta do init não contém nenhum upload_url.

Por quanto tempo o upload_url vale?

Uma hora. A nota do TikTok nos dois endpoints de init diz: "The upload_url is valid for one hour after issuance. The upload must be completed in this time range." Depois disso, novos chunks devolvem 403 Forbidden, e a correção é uma chamada de init nova em vez de uma retentativa, do mesmo jeito que uma URN de upload do LinkedIn vencida força um novo registro.

Um vídeo entre 5 MB e 64 MB precisa ser dividido em vários chunks?

A regra de múltiplos chunks do TikTok só entra em ação acima de 64 MB, e a regra de chunk único cobre apenas arquivos com menos de 5 MB. Um arquivo nessa faixa intermediária cabe em um único chunk sem violar nenhum dos dois limites, então um único PUT com chunk_size igual ao tamanho do arquivo atende as duas regras. O Media Transfer Guide não diz nada que obrigue a divisão antes de o arquivo passar de 64 MB.

chunk_size é obrigatório no endpoint Direct Post do TikTok?

A referência do Direct Post do TikTok deixa a coluna de obrigatoriedade em branco para chunk_size e total_chunk_count, diferente do endpoint de Upload, que marca os três campos como "true for FILE_UPLOAD". O TikTok nunca afirma que esses dois campos são opcionais no Direct Post, e publica as regras de chunk uma única vez para os dois endpoints. Trate as células em branco como uma lacuna na documentação e envie os três campos, não importa qual endpoint de init você use.

Qual é a duração máxima de vídeo aceita pela API do TikTok?

4 GB e 10 minutos, os dois limites que o TikTok define antes mesmo de qualquer cálculo de chunk. Esse teto importa porque o limite do TikTok para vídeos dentro do app já cresceu bem além desse número, então um vídeo que cabe no app ainda pode ser rejeitado pela API. Confira os dois limites antes de calcular um único valor de chunk_size.

O que fazer quando o envio de um chunk retorna um erro 5xx?

Reenviar o mesmo chunk. A própria descrição do TikTok para o status 5xx diz "Gateway connection error or TikTok Internal error. You should retry submitting this chunk.", e a upload_url continua válida para essa nova tentativa enquanto ainda estiver dentro da janela de uma hora. Não é preciso recalcular chunk_size nem reiniciar o arquivo por causa de um erro do lado do servidor.