Posts

Publicar Shorts no YouTube pela API

Um POST /posts com a conexão youtube e o format shorts envia o vídeo para o canal que o cliente conectou. Seu produto não implementa o OAuth do YouTube nem guarda tokens: manda a URL do vídeo e o Connect publica em segundo plano, no mesmo endpoint das outras redes.

A chamada

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "video-88",
  "format": "shorts",
  "caption": "Behind the scenes of our latest shoot.",
  "media": [
    {
      "type": "video",
      "url": "https://cdn.example.com/short.mp4"
    }
  ],
  "youtube": {
    "title": "Behind the scenes",
    "privacy_status": "public",
    "category_id": "<category id>",
    "tags": [
      "bts",
      "making of"
    ],
    "made_for_kids": false,
    "notify_subscribers": true
  }
}

O que dá para fazer

  • Publicar um vídeo curto no canal, com título e descrição.
  • Escolher a visibilidade: public, unlisted ou private.
  • Listar as categorias atribuíveis com GET /posts/youtube/categories e usar o id em youtube.category_id.
  • Definir tags, a marcação de conteúdo para crianças (made_for_kids) e a notificação aos inscritos.
  • Escolher o canal pela conexão (customer_integration) ou pelo source_name.

Regras e limites

  • O format é sempre shorts, com exatamente 1 vídeo e sem alt_text.
  • youtube.title (até 100 caracteres) e youtube.privacy_status são obrigatórios. Título e descrição não aceitam < e >.
  • A descrição (caption) vai até 5000 bytes. As tags não aceitam <, > e vírgula, e somam até 500 caracteres.
  • O YouTube decide se é um Short pelo próprio vídeo: vertical e de até 3 minutos.
  • O POST /posts responde 202 e a publicação roda depois. Acompanhe por GET /posts/{uuid}.
  • Vídeos acima de 8 MB podem ser enviados antes em partes pelo módulo de mídia, que devolve a URL para usar em media.url.

Campos principais

CampoTipoObrigatórioDescrição
external_referencestringSimO id do vídeo no seu sistema (até 100 caracteres). Impede publicar o mesmo vídeo duas vezes no mesmo canal.
formatstringSimSempre shorts no YouTube.
captionstringNãoVira a descrição do vídeo. Até 5000 bytes, sem < e >.
mediaarraySimExatamente 1 vídeo, sem alt_text.
youtube.titlestringSimTítulo do vídeo, até 100 caracteres, sem < e >.
youtube.privacy_statusstringSimVisibilidade: public, unlisted ou private.
youtube.category_idstringNãoCategoria do vídeo. Vem de GET /posts/youtube/categories.
youtube.tagsarrayNãoTags do vídeo, sem <, > e vírgula. Juntas, até 500 caracteres.
youtube.made_for_kidsbooleanNãoDeclara o vídeo como feito para crianças.
youtube.notify_subscribersbooleanNãoNotifica os inscritos do canal.

Para quem

  • Plataforma de criadores

    O criador grava uma vez e o produto publica o Short no canal conectado, com título, tags e visibilidade definidos.

  • Reaproveitamento de vídeo curto

    Uma ferramenta de social media envia o mesmo vídeo vertical para Reels e YouTube Shorts em chamadas separadas.

  • Agente de IA de vídeo

    Um agente gera o vídeo e os metadados, escolhe a categoria em GET /posts/youtube/categories e publica como private para revisão.

Funciona com

  • YouTube

Perguntas frequentes

Como o YouTube sabe que é um Short?

Pelo próprio vídeo: vertical e de até 3 minutos. Você envia format shorts e o YouTube decide.

Como descubro o category_id?

Chame GET /posts/youtube/categories com a conexão ou o source_name. region_code (padrão BR) e hl ajustam o país e o idioma dos títulos.

Posso publicar como privado primeiro?

Sim. youtube.privacy_status aceita public, unlisted ou private.

Relacionadas

Ver tudo que dá para fazer em Posts

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.