> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API do YouTube
> Opções para publicar usando a API do YouTube
Publicar no YouTube requer que sua conta do YouTube tenha pelo menos um Channel e você seja proprietário desse Channel.
Para criar um YouTube Channel, clique em seu perfil no YouTube Dashboard e escolha "Create a Channel".
Você também pode usar este link direto para criar um YouTube Channel: [http://m.youtube.com/create\_channel](http://m.youtube.com/create_channel)
Se estiver tendo problemas para visualizar canais do YouTube, consulte o [guia de solução de problemas de canais do YouTube](/help-center/technical-support/youtube_channels_not_showing).
Falhas de upload no YouTube podem retornar os códigos de erro **453** (timeout) ou **454**
(service unavailable) com `retryAvailable: true`. Sua integração pode ramificar
com base nesse flag para reenviar automaticamente falhas transitórias com backoff. Veja a
[referência de códigos de erro](/errors/errors-ayrshare) para a lista completa.
Consulte as [Diretrizes de mídia do YouTube](/media-guidelines/youtube) e a [Autorização do YouTube](/dashboard/connect-social-accounts/youtube) para mais informações.
## Publicando no YouTube
### Visão geral da publicação
Publicar usando a API do YouTube requer o objeto `youTubeOptions` com pelo menos um parâmetro `title` — máximo de 100 caracteres.
O `title` é o único campo obrigatório e pode ser gerado automaticamente com o [endpoint transcribe](/apis/generate/transcribe-video).
Por exemplo, para publicar um vídeo do YouTube com configurações padrão:
```json YouTube Post theme={"system"}
{
// Required: Video description
"post": "My Best YouTube Description", // empty string is allowed
// Required: Platform to post to
"platforms": ["youtube"],
// Required: URL of video (only 1 allowed)
"mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"],
"youTubeOptions": {
// Required: Video title (max 100 characters)
"title": "Your Best Title"
}
}
```
Vídeos do YouTube são `private` por padrão, mas a visibilidade pode ser definida como `public` ou `unlisted`.
Consulte os campos opcionais abaixo para mais detalhes.
### Campos opcionais da publicação no YouTube
Há vários outros campos opcionais listados abaixo, incluindo a `visibility` do vídeo, `tags` e a data `publishAt`. Consulte os comentários para requisitos e descrições.
```json YouTube Post Optional Fields theme={"system"}
{
// Required fields
"post": "My Best YouTube Description", // Video description, up to 5,000 characters
"platforms": ["youtube"], // Platform to post to
"mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"], // URL of video (1 allowed)
"youTubeOptions": {
// Required fields
"title": "Your Best Title", // Video Title (max 100 characters)
/** Optional Fields **/
// Visibility: "public", "unlisted", or "private" (default: "private")
"visibility": "private",
// Thumbnail settings - JPEG/PNG URL under 2MB, must end in png/jpg/jpeg
"thumbNail": "https://img.ayrshare.com/012/gb.jpg",
// Video organization
"playListId": "PLrav6EfwgDX5", // Playlist ID to add the video
"tags": ["dancing", "dogs"], // Tag array (400 chars total, 2+ chars each)
// Video settings
"madeForKids": false, // Self-declared kids content (default: false)
"license": "youtube", // "youtube" (default) or "creativeCommon"
"embeddable": true, // default: true
"publicStatsViewable": true, // default: true
"shorts": true, // Post as YouTube Short (max 3 minutes, adds #shorts)
"notifySubscribers": true, // Send notification to subscribers (default: true)
"categoryId": 24, // Video category (24 = Entertainment)
"containsSyntheticMedia": true, // Disclose that a video contains realistic Altered or Synthetic (A/S) content
// YouTube controlled publishing - UTC publish time. See below for details.
"publishAt": "2022-10-08T21:18:36Z",
}
}
```
O `title` deve ter 100 caracteres ou menos. O `post` deve ter 5.000 caracteres ou menos. O `post` e o `title` podem conter quaisquer caracteres, exceto `<` e `>`.
O Playlist Id pode ser encontrado abrindo a playlist em um navegador e copiando o valor após `list=`. O usuário autenticado e o canal devem ser os proprietários da playlist para adicionar vídeos.
Se seu vídeo não terminar em uma extensão de vídeo conhecida, como mp4, use o parâmetro `isVideo`. Consulte o [endpoint /post](/apis/post/post) para detalhes.
O campo `publishAt` permitirá que o YouTube controle o horário de publicação.
O vídeo permanecerá privado até o horário de publicação, quando será tornado público.
Se o horário de publicação estiver no passado, o vídeo será tornado público imediatamente.
Não use o campo `scheduleDate` de post quando estiver usando o campo `publishAt`.
O campo `containsSyntheticMedia` é usado para divulgar que um vídeo contém conteúdo realista Alterado ou Sintético (A/S): faz uma pessoa real parecer dizer ou fazer algo que ela realmente não disse nem fez, altera imagens de um evento ou local real, ou gera uma cena com aparência realista que não ocorreu de fato.
`license` - Define o tipo de licença do vídeo. Valores aceitos: `"youtube"` (Licença padrão do YouTube, padrão) ou `"creativeCommon"` (Creative Commons - Attribution).
`embeddable` - Booleano (ou as strings `"true"` / `"false"`). Controla se o vídeo pode ser incorporado em sites de terceiros. Padrão: `true`.
`publicStatsViewable` - Booleano (ou as strings `"true"` / `"false"`). Controla se o **painel de estatísticas estendidas** na página de reprodução do vídeo é visível publicamente. A contagem básica de visualizações e likes permanece publicamente visível independentemente desta configuração. Padrão: `true`. Consulte [`status.publicStatsViewable` na referência da YouTube Data API](https://developers.google.com/youtube/v3/docs/videos#status.publicStatsViewable) para detalhes.
Consulte as [Diretrizes de mídia do YouTube](/media-guidelines/youtube) para mais informações.
**Monetização e controles de conteúdo**
Os campos `madeForKids`, `license`, `embeddable` e `publicStatsViewable` podem ser definidos via API do Ayrshare no momento do upload. Contudo, controles diretos de monetização (ativar/desativar anúncios), seleção de tipo de anúncio (pre-roll, mid-roll, post-roll), compartilhamento de receita e Content ID exigem credenciais do YouTube CMS — disponíveis apenas para MCNs e proprietários de conteúdo empresarial — e **não** estão disponíveis através do OAuth padrão do YouTube ou da API do Ayrshare.
## YouTube Shorts
Um YouTube Short é um vídeo vertical de curta duração, que pode ter até três minutos.
Eles são semelhantes aos vídeos do TikTok e aos Reels do Instagram ou Facebook.
### Publicando YouTube Shorts
Você pode publicar um vídeo YouTube Shorts de até 3 minutos adicionando o parâmetro `shorts` ao objeto `youTubeOptions`.
```json YouTube Shorts Post theme={"system"}
{
"youTubeOptions": {
"shorts": true
}
}
```
A hashtag #shorts será adicionada à descrição do YouTube.
### Informações importantes sobre YouTube Shorts
Enviar um vídeo como Short é uma indicação ao YouTube de que você gostaria que o vídeo aparecesse
como Short, mas não garante que ele apareça como Short. O vídeo deve atender aos requisitos de [Short
video](/media-guidelines/youtube#shorts), como ter 3 minutos ou menos e
proporção vertical de 9:16 para ser considerado Short pelo YouTube.
YouTube Shorts não suportam thumbnails.
Informações adicionais sobre uso da [API para publicar YouTube
Shorts](https://www.ayrshare.com/blog/post-youtube-shorts-with-an-api/).
## Thumbnails do YouTube
Thumbnails personalizadas exigem um **canal do YouTube verificado**. O motivo mais comum para uma thumbnail não ser aplicada (embora o vídeo ainda seja publicado) é um canal não verificado — verifique em [https://www.youtube.com/verify](https://www.youtube.com/verify) (verificação por telefone). Sua `thumbNail` também deve ser um **PNG ou JPG/JPEG**, **2MB ou menos** e servida a partir de uma **URL acessível**; o Ayrshare valida isso antes de publicar, quando possível. Quando um vídeo é publicado, mas a thumbnail falha, o resultado do YouTube mantém `status: "success"` e adiciona um array `warnings` (`feature: "thumbnail"`, `code: 307`) descrevendo a falha. Consulte [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_unverified_channel) para a solução completa.
### Adicionando thumbnails do YouTube
Thumbnails do YouTube e outros recursos, como enviar vídeos de 15 minutos, exigem a verificação do seu número de telefone.
Uma `thumbNail` é uma URL de um JPEG ou PNG com menos de 2MB de tamanho. A extensão do arquivo deve terminar em png, jpg ou jpeg.
```json YouTube Thumbnail theme={"system"}
{
"youTubeOptions": {
"thumbNail": "https://img.ayrshare.com/012/gb.jpg"
}
}
```
YouTube Shorts atualmente não suportam thumbnails.
### Habilitar thumbnails no YouTube Studio
Você precisa ter permissões do YouTube para publicar thumbnails. No [YouTube Studio](https://studio.youtube.com/), acesse *Settings->Channel*. Selecione "*Feature Eligibility*" e clique em "*Features that require phone verification*". Insira seu número de telefone para habilitar.
O YouTube pode levar até 24 horas para habilitar thumbnails após você verificar seu número de telefone. Observe que o YouTube determina a elegibilidade para adicionar thumbnails. A verificação de telefone "habilitada" não garante que o YouTube permitirá o upload de thumbnails.
Se você foi verificado há 24 horas e ainda tem problemas, verifique:
1. Se você consegue enviar thumbnails manualmente no YouTube Studio.
2. Se estiver trabalhando com uma Brand Content Owner Account (frequentemente usada por canais de empresas ou organizações), certifique-se de ter as permissões necessárias. Recomendamos direitos de "Owner".
3. Se ainda estiver com problemas, veja este vídeo sobre [como resolver o problema de thumbnail](https://www.youtube.com/watch?v=1bFmX2uQk0Y).
## Vídeo: Publicando no YouTube via API
## Limites de upload
O YouTube limita a quantidade de vídeos que um canal pode enviar em um período de 24 horas via API do YouTube.
Dependendo da localização de um criador, um canal pode conseguir aumentar seu limite diário
obtendo acesso a recursos avançados. Para saber mais, acesse este
[artigo](https://notifications.google.com/g/p/ACnX6LbjUElgT-OfRLVjenkpdldv6pIJ5JYGZyPGTdJwRYmo3fXFkfXJsPGnswgns0BjJ6Bjxn2bqpqfBt6gBdkLoqESKA7mqLNllzcR2qnYUJn5KlJN5jPqCWl6DGr58cZEt94mMvxXATN6_PaBR1RYEpNMTYWN).
Os limites podem variar por país/região ou histórico do canal. Notificações de violação de direitos autorais podem afetar a
elegibilidade do histórico do canal, e [notificações das Diretrizes da Comunidade](https://support.google.com/youtube/answer/2802032) afetarão o quanto um canal pode
fazer upload.
Se você receber um erro de limite de upload, aguarde e tente novamente em 24 horas.
## Links na descrição
Você deve ativar os **Recursos avançados** no YouTube Studio para ter links clicáveis na descrição do vídeo do YouTube.
Vá em **YouTube Studio -> Settings -> Channel -> Feature Eligibility -> Advanced Features -> Access Features** para ativar os recursos avançados.
## Playlists
Você pode adicionar vídeos a uma playlist do YouTube incluindo o `playListId` no objeto `youTubeOptions`.
Certifique-se de que o usuário autenticado e o canal sejam os proprietários da playlist.
```json YouTube Playlist theme={"system"}
{
"youTubeOptions": {
"playListId": "PLrav6EfwgDX5"
}
}
```
## Legendas / Captions para vídeos
Você pode adicionar legendas do YouTube, também conhecidas como captions do YouTube, aos vídeos incluindo um [arquivo SRT](https://en.wikipedia.org/wiki/SubRip) ou um [arquivo SBV](https://support.google.com/youtube/answer/2734698) do YouTube. Use o campo `subTitleUrl` no objeto `youTubeOptions` para especificar a URL do seu arquivo SRT ou SBV.
```json YouTube Subtitles theme={"system"}
{
"youTubeOptions": {
"title": "My new post from Ayrshare to Youtube",
"subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
"subTitleLanguage": "en",
"subTitleName": "English"
}
}
```
`subTitleUrl`: Um arquivo SRT ou SBV válido. A URL deve começar com `https://` e terminar em `.srt` ou
`.sbv` e ser um arquivo SRT ou SBV válido. O arquivo deve ter menos de 100 MB.
`subTitleLanguage`: Opcional: O idioma das legendas. Deve ser um [código de idioma](/iso-codes/language)
válido. Padrão: "en".
`subTitleName`: Opcional: O nome da faixa de legenda. O nome se destina a ficar visível para
o usuário como opção durante a reprodução. O tamanho máximo suportado é de 150 caracteres.
Padrão: "English".
**O que são arquivos SRT e SBV?**
SRT (SubRip Subtitle) e SBV (YouTube SubViewer) são formatos de arquivo de legenda usados para exibir
texto sincronizado em vídeos. A principal diferença é que o SRT usa timestamps no formato HH:MM:SS,MS com
setas como separadores, enquanto o SBV usa o formato HH:MM:SS.MS com vírgulas.
```text theme={"system"}
## SRT Format Example
1
00:00:01,000 --> 00:00:04,000
Welcome to our tutorial on subtitle formats.
2
00:00:04,500 --> 00:00:08,000
Today we'll learn about SRT and SBV files.
## SBV Format Example
0:00:01.000,0:00:04.000
Welcome to our tutorial on subtitle formats.
0:00:04.500,0:00:08.000
Today we'll learn about SRT and SBV files.
```
## Tags
Você pode adicionar tags do YouTube aos seus vídeos incluindo o array `tags` no objeto `youTubeOptions`.
Cada tag deve ter pelo menos 2 caracteres, e o tamanho total de todas as tags deve ser de 500 caracteres ou menos.
```json YouTube Tags theme={"system"}
{
"youTubeOptions": {
"tags": ["dancing", "dogs"]
}
}
```
## Menções no YouTube
Embora você possa adicionar um `@handle` a uma publicação do YouTube, o YouTube não suporta a resolução de menções no texto da publicação.
O `@handle` permanecerá como texto simples.
## Limites de caracteres
Consulte [Limites de caracteres do YouTube](/help-center/technical-support/character_limits#youtube-character-limits) para mais informações.
## Endpoints adicionais
## Playlists
Você pode adicionar vídeos a uma playlist do YouTube incluindo o `playListId` no objeto `youTubeOptions`.
Certifique-se de que o usuário autenticado e o canal sejam os proprietários da playlist.
```json YouTube Playlist theme={"system"}
{
"youTubeOptions": {
"playListId": "PLrav6EfwgDX5"
}
}
```
## Legendas / Captions para vídeos
Você pode adicionar legendas do YouTube, também conhecidas como captions do YouTube, aos vídeos incluindo um [arquivo SRT](https://en.wikipedia.org/wiki/SubRip) ou um [arquivo SBV](https://support.google.com/youtube/answer/2734698) do YouTube. Use o campo `subTitleUrl` no objeto `youTubeOptions` para especificar a URL do seu arquivo SRT ou SBV.
```json YouTube Subtitles theme={"system"}
{
"youTubeOptions": {
"title": "My new post from Ayrshare to Youtube",
"subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
"subTitleLanguage": "en",
"subTitleName": "English"
}
}
```