Como funciona o máximo de itens no carrossel da API do Threads

Qual é o limite de máximo de itens no carrossel da API do Threads?

A Meta fixa o máximo de itens no carrossel da API do Threads em 20 filhos, com piso de 2, e enuncia o par quatro vezes ao longo de duas páginas. O guia de posts abre sua seção de carrossel com "You may publish up to 20 images, videos, or a mix of the two in a carousel post", e depois lista a regra mais duas vezes sob Limitations: "Carousels are limited to 20 images, videos, or a mix of the two" e "Carousels require a minimum of two children."

A página de visão geral enuncia a mesma coisa em uma linha sob Other Limitations: "Carousel posts must have a maximum of 20 children and a minimum of 2 children." A descrição do parâmetro children repete pela quarta vez: "Carousels must have at least 2 and no more than 20 total images, videos, or a mix of the two."

Quatro enunciados, um número. Esse nível de concordância é incomum na documentação de publicação da Meta e significa que uma integração pode cravar a verificação de limites sem se preocupar com qual página está desatualizada.

Quando o teto de carrossel do Threads virou 20?

Em 19 de setembro de 2024, e a Meta registrou a mudança no changelog do Threads: "Carousel posts are now allowed up to 20 images, videos, or a mix of the two." Antes dessa entrada o teto era 10, igual ao do Instagram.

Essa data importa ao auditar código antigo. Um 10 cravado no código é a primeira coisa a procurar em qualquer integração do Threads escrita antes de setembro de 2024 ou portada de uma biblioteca de publicação do Instagram, porque ele parte em silêncio um conjunto de 16 imagens em dois posts que queimam um lugar cada na cota diária de publicação.

Como funciona o fluxo de contêiner por item?

Publicar um carrossel do Threads leva três chamadas, uma a mais que um post avulso. A Meta descreve como criar "the individual media containers for each image and video", depois "a single carousel container to contain the media containers", e então a publicação.

O passo 1 cria um contêiner por item. O parâmetro que distingue é is_carousel_item=true, e o media_type aceita IMAGE ou VIDEO aqui:

curl -i -X POST \
  -d "image_url=<IMAGE_URL>" \
  -d "is_carousel_item=true" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Cada chamada devolve um ID de contêiner. Repita para cada item, até 20.

O passo 2 cria o contêiner do carrossel em si, com media_type=CAROUSEL e uma lista children separada por vírgulas com os IDs do passo 1. O text do post pertence a esta chamada, não aos itens individuais:

curl -i -X POST \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>,..." \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

O passo 3 publica o contêiner do carrossel passando o ID dele como creation_id para POST /{threads-user-id}/threads_publish, que devolve o ID da mídia publicada. A Meta aconselha esperar "on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload", e para itens de vídeo recomenda consultar GET /{threads-container-id}?fields=status,error_message "once per minute, for no more than 5 minutes".

Onde as próprias páginas da Meta discordam sobre itens de carrossel?

O is_carousel_item recebe duas classificações diferentes em duas páginas no ar. O guia de posts o marca como "Required" na tabela de parâmetros para posts avulsos, com os valores true e false (default). A referência de POST /{threads-user-id}/threads marca o mesmo parâmetro como "Optional", com os valores true e false (default).

Como as duas páginas concordam que o padrão é false, a referência é a coerente: um parâmetro com valor padrão não pode ser obrigatório. A mesma tabela na seção do carrossel também carrega uma nota copiada da tabela de post avulso, "CAROUSEL is not available for single thread posts", que é verdade mas não tem nada a ver com um item de carrossel. Leia as tabelas de parâmetros para os valores e a referência para saber se um campo é obrigatório.

O que um carrossel grande demais devolve?

A Meta não documenta nenhum erro para uma lista children que rompe os limites. O índice da Threads API Reference lista nove páginas de endpoint e nenhuma página de códigos de erro, e developers.facebook.com/documentation/threads/reference/error-codes não resolve. A página de troubleshooting cobre só duas coisas: valores de status do contêiner e falhas de processamento de mídia.

Cada um deles descreve um arquivo de mídia, não uma lista de filhos malformada. O único código de erro no caminho de publicação que a Meta nomeia em toda a documentação do Threads é THREADS_API__LINK_LIMIT_EXCEEDED, que dispara quando um post carrega mais de cinco links.

Então não há nada para capturar pelo nome. Valide o tamanho de children antes da chamada do passo 2, rejeite localmente qualquer coisa abaixo de 2 ou acima de 20, e trate o que a API devolver para uma lista fora dos limites como comportamento não documentado que pode mudar sem entrada de changelog.

Um carrossel conta como um post ou como vinte?

Um. A Meta diz isso nos dois lugares em que a regra poderia ser procurada: "Carousel posts count as a single post against a profile's rate limit" na seção do carrossel, e "Publishing a carousel counts as a single post" na nota acima do Step 3.

Isso faz do carrossel a maior alavanca que alguém tem sobre o volume de publicação no Threads. Um perfil limitado a 250 posts publicados pela API dentro de um período móvel de 24 horas pode mover 5,000 peças de mídia se toda publicação for um carrossel cheio de 20 itens, contra 250 se cada post carregar uma imagem. Vinte posts avulsos custam vinte lugares; as mesmas vinte imagens em um carrossel custam um.

Como o carrossel do Threads se compara ao do Instagram?

Os dois rodam na infraestrutura da Meta e nenhum teto bate com o outro. O guia de publicação de conteúdo do Instagram afirma "Carousels are limited to 10 images, videos, or a mix of the two", metade do número do Threads, e a cota de publicação também é menor.

Publicar o mesmo conjunto nos dois exige, portanto, uma regra de divisão, já que um carrossel de 18 imagens do Threads não cabe em um post do Instagram. A aritmética do lado do Instagram, incluindo a segunda frase de contagem de posts que a Meta deixa em aberto na própria página, está coberta em o limite de 100 posts por 24 horas da API do Instagram.

O que cada item do carrossel precisa satisfazer?

O teto de 20 itens é uma contagem, não um orçamento de tamanho, e cada filho é validado por conta própria contra as mesmas especificações de mídia que regem posts avulsos. Imagens precisam ser JPEG ou PNG, no máximo 8 MB, proporção dentro de 10:1, com largura mínima de 320 e máxima de 1440, que a Meta reduz automaticamente. Vídeos precisam ser MOV ou MP4, no máximo 1 GB, no máximo 300 segundos, de 23 a 60 FPS, com no máximo 1920 pixels na horizontal.

Um único filho grande demais derruba o próprio contêiner no passo 1, o que faz o contêiner do carrossel nunca ser montado. Validar a mídia antes da primeira chamada é mais barato que descobrir no passo 2 que um de dezenove IDs está faltando, hábito que vale para posts em carrossel em qualquer rede.

O texto do post tem teto próprio de 500 caracteres no contêiner do carrossel, regido pelas mesmas regras cobertas em como o limite de 500 caracteres da API do Threads trata a topic_tag.

Perguntas frequentes

Um carrossel do Threads pode misturar imagens e vídeos?

Sim. A redação da Meta é "20 images, videos, or a mix of the two" em toda página que enuncia o limite, então um carrossel pode ter qualquer combinação desde que o total fique entre 2 e 20 e cada item atenda à sua especificação de mídia.

Qual é o número mínimo de itens em um carrossel do Threads?

Dois. A Meta afirma "Carousels require a minimum of two children" no guia de posts e repete na página de visão geral como "a minimum of 2 children". Um carrossel de item único não é um contêiner válido, então publique uma imagem como post IMAGE normal.

Um carrossel de 20 itens usa 20 lugares da cota diária de publicação?

Não. A Meta afirma que "Carousel posts count as a single post against a profile's rate limit", então um carrossel cheio de 20 itens gasta uma das 250 publicações disponíveis em um período móvel de 24 horas.

Onde vai o texto de um post em carrossel?

No contêiner do carrossel criado no passo 2, onde o text é listado como parâmetro opcional ao lado de media_type=CAROUSEL e children. Os contêineres de item do passo 1 também aceitam text, e a Meta nunca diz o que esse valor faz em um item de carrossel.

Criar contêineres de item de carrossel conta contra alguma cota?

A Meta aplica o limite de publicação "on the POST /{threads-user-id}/threads_publish endpoint", que é o passo 3, então os contêineres de item do passo 1 e o contêiner do carrossel do passo 2 não gastam cota de publicação. Contêineres expiram: um não publicado devolve EXPIRED, descrito como "The container was not published within 24 hours and has expired."

Onde o limite de 20 itens no carrossel está documentado?

Em quatro lugares ao longo de duas páginas da Meta. O guia de posts em developers.facebook.com/documentation/threads/posts o enuncia na introdução do carrossel, na lista de Limitations e na descrição do parâmetro children; a página de visão geral em developers.facebook.com/documentation/threads/overview o enuncia sob Other Limitations. A mudança de 10 para 20 está registrada no changelog do Threads em 19 de setembro de 2024.

O parâmetro is_carousel_item é obrigatório ou opcional?

As próprias páginas da Meta se contradizem aqui. O guia de posts marca esse parâmetro como "Obrigatório" na sua tabela, enquanto a referência de POST /{threads-user-id}/threads marca o mesmo parâmetro como "Opcional" com valor padrão false. Como as duas páginas concordam nesse valor padrão, um parâmetro com valor padrão não pode ser obrigatório, então a página de referência é a que vale seguir.

Quais formatos de arquivo e limites de tamanho valem para um item de carrossel do Threads?

Cada item é validado com as mesmas especificações de mídia de um post individual, não importa o carrossel em que esteja. Imagens precisam ser JPEG ou PNG, de até 8 MB, com proporção dentro de 10:1. Vídeos precisam ser MOV ou MP4, de até 1 GB e 300 segundos, entre 23 e 60 FPS.

Quanto tempo esperar antes de publicar um contêiner de carrossel?

A Meta recomenda esperar cerca de 30 segundos depois de criar um contêiner antes de chamar threads_publish, para dar tempo aos servidores de processar o upload. Para itens de vídeo, é preciso consultar GET /{threads-container-id}?fields=status,error_message uma vez por minuto, por no máximo 5 minutos, antes de considerar o contêiner pronto.

Existe um código de erro nomeado para um carrossel com itens demais ou de menos?

A Meta não documenta nenhum. O único código de erro de publicação que a Meta nomeia em toda a documentação do Threads é THREADS_API__LINK_LIMIT_EXCEEDED, que dispara quando um post carrega mais de cinco links. Uma lista children fora da faixa de 2 a 20 não gera nenhum erro documentado, então vale validar o tamanho localmente antes da chamada do passo 2.