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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| external_reference | string | Sim | O id do vídeo no seu sistema (até 100 caracteres). Impede publicar o mesmo vídeo duas vezes no mesmo canal. |
| format | string | Sim | Sempre shorts no YouTube. |
| caption | string | Não | Vira a descrição do vídeo. Até 5000 bytes, sem < e >. |
| media | array | Sim | Exatamente 1 vídeo, sem alt_text. |
| youtube.title | string | Sim | Título do vídeo, até 100 caracteres, sem < e >. |
| youtube.privacy_status | string | Sim | Visibilidade: public, unlisted ou private. |
| youtube.category_id | string | Não | Categoria do vídeo. Vem de GET /posts/youtube/categories. |
| youtube.tags | array | Não | Tags do vídeo, sem <, > e vírgula. Juntas, até 500 caracteres. |
| youtube.made_for_kids | boolean | Não | Declara o vídeo como feito para crianças. |
| youtube.notify_subscribers | boolean | Não | Notifica 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
