Como usar a API do Vidiome para automatizar a geração de artigos a partir de vídeo

A API REST do Vidiome transforma um vídeo do YouTube em um artigo de blog estruturado com uma única requisição. Você envia uma URL do YouTube, o Vidiome lê a transcrição do vídeo, escreve o artigo com um LLM e o devolve em JSON: um título e uma lista de seções, cada uma com seu próprio título H2, conteúdo e marcações de tempo.

Este tutorial aborda a autenticação, o formato da requisição e da resposta, exemplos com curl e Node.js, o processamento em lote, a publicação no WordPress e os limites que você precisa levar em conta.

Para quem é este tutorial

• Desenvolvedores SaaS que criam recursos de automação de conteúdo para clientes ou ferramentas internas
• Agências de conteúdo que processam muitos vídeos por semana e querem eliminar as etapas manuais
• Equipes de plataforma que integram a conversão de vídeo em artigo a um CMS ou fluxo de conteúdo existente

Se você é criador e não desenvolvedor, o aplicativo web do Vidiome é o caminho mais rápido. Ele também captura uma imagem para cada seção, o que a API não faz.

Pré-requisitos

• Uma conta Vidiome com um plano pago (Starter, Pro ou Business). Requisições à API feitas por contas gratuitas são recusadas com 403.
• Uma chave de API, criada no aplicativo em Perfil → Chaves API. As chaves começam com vdm_live_. Mantenha-as em segredo: qualquer pessoa com a chave pode gastar seus créditos.
• Um vídeo do YouTube que tenha transcrição (legendas manuais ou automáticas). A API trabalha a partir dessa transcrição.

Contas novas recebem 120 créditos grátis para testar o aplicativo web antes de escolher um plano.

---

Endpoint: POST /api/v1/articles

Requisição

POST https://www.vidiome.com/api/v1/articles
Content-Type: application/json
x-api-key: vdm_live_YOUR_KEY

Authorization: Bearer vdm_live_YOUR_KEY também funciona.

Corpo da requisição

{
  "youtubeUrl": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "language": "pt"
}

Campo	Tipo	Obrigatório	Descrição
youtubeUrl	string	Sim	URL completa de um vídeo do YouTube
language	string	Não	Idioma em que o artigo é escrito: en, fr, es, pt, de, ru, hi, uk, id ou tr. Informe-o sempre: sem ele, nenhum idioma é imposto

Essa é a requisição inteira. Não existe parâmetro de upload de arquivo, de formato de saída nem de palavra-chave.

Resposta

A chamada é síncrona: a conexão fica aberta enquanto o Vidiome gera o artigo e, em seguida, o resultado completo é retornado. Conte com algo entre alguns segundos e alguns minutos, dependendo da duração do vídeo.

{
  "id": "5b0c9c2e-6f1d-4d8a-9a57-2f1f3c1e8b21",
  "title": "Como transformar um vídeo em um mês de conteúdo",
  "sections": [
    {
      "id": "a3f1…",
      "title": "Introdução: um vídeo, vários formatos",
      "content": "A maioria dos criadores publica um vídeo e segue em frente…\n\n### Por que a transcrição é só um ponto de partida\n\n…",
      "startTime": 0,
      "endTime": 74,
      "images": []
    }
  ],
  "videoUrl": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "videoId": "XXXXXXXXXXX",
  "language": "pt",
  "creditsUsed": 40,
  "creditsRemaining": 460,
  "createdAt": "2026-09-26T10:23:41.000Z"
}

Alguns pontos importantes sobre a resposta:

• sections vêm na ordem de leitura: uma introdução, as seções do corpo e depois uma conclusão. title é o H2 da seção. content é texto com linhas ### para os subtítulos H3, linhas em branco entre os parágrafos, **negrito** e itens de lista - .
• startTime / endTime estão em segundos e indicam o trecho do vídeo de onde vem cada seção. Útil para incorporar o vídeo no momento certo.
• images está sempre vazio pela API. As capturas de tela são feitas no navegador pelo aplicativo web. Para adicioná-las, abra o artigo no Vidiome e escolha-as lá, ou use suas próprias imagens.
• O artigo é salvo na sua conta (id). Ele aparece no seu painel do Vidiome, onde você pode editá-lo.

---

Exemplos de código

curl

curl -X POST https://www.vidiome.com/api/v1/articles \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VIDIOME_API_KEY" \
  -d '{
    "youtubeUrl": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
    "language": "pt"
  }'

Node.js (fetch)

const VIDIOME_API_KEY = process.env.VIDIOME_API_KEY;

async function generateArticle(youtubeUrl, language = 'pt') {
  const response = await fetch('https://www.vidiome.com/api/v1/articles', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': VIDIOME_API_KEY,
    },
    body: JSON.stringify({ youtubeUrl, language }),
    // A geração pode levar alguns minutos: o cliente não deve desistir antes.
    signal: AbortSignal.timeout(6 * 60 * 1000),
  });

  const data = await response.json();
  if (!response.ok) {
    const error = new Error(`Vidiome API ${response.status}: ${data.error}`);
    error.status = response.status;
    error.retryAfter = Number(response.headers.get('retry-after')) || null;
    throw error;
  }
  return data;
}

// Converte as seções em Markdown (ou passe-as para o seu próprio renderizador).
function toMarkdown(article) {
  const body = article.sections
    .map((section) => `## ${section.title}\n\n${section.content}`)
    .join('\n\n');
  return `# ${article.title}\n\n${body}\n`;
}

const article = await generateArticle('https://www.youtube.com/watch?v=XXXXXXXXXXX');
console.log(toMarkdown(article));
console.log(`Credits used: ${article.creditsUsed}, left: ${article.creditsRemaining}`);

---

Fluxo de automação

┌─────────────────────────────────────────────────────────┐
│                    ORIGEM DOS VÍDEOS                    │
│  Playlist / canal do YouTube / lista de URLs            │
└──────────────────────┬──────────────────────────────────┘
                       │  URLs do YouTube
                       ▼
┌─────────────────────────────────────────────────────────┐
│                       ORQUESTRAÇÃO                      │
│  Cron job / n8n / Make.com / sua própria fila           │
│  - Pular URLs já processadas                            │
│  - Ficar abaixo de 10 requisições por minuto por chave  │
│  - Tentar de novo em 429 / 502 após o Retry-After       │
└──────────────────────┬──────────────────────────────────┘
                       │  POST /api/v1/articles
                       ▼
┌─────────────────────────────────────────────────────────┐
│                      API DO VIDIOME                     │
│  1. Buscar a transcrição do vídeo do YouTube            │
│  2. Escrever o artigo com um LLM                        │
│  3. Salvar na sua conta, retornar título + seções       │
└──────────────────────┬──────────────────────────────────┘
                       │  JSON do artigo
                       ▼
┌─────────────────────────────────────────────────────────┐
│                    PÓS-PROCESSAMENTO                    │
│  - Converter as seções em HTML ou Markdown              │
│  - Revisão humana (recomendada)                         │
│  - Imagens, links internos, meta description, schema    │
└──────────────────────┬──────────────────────────────────┘
                       │  Artigo pronto para publicar
                       ▼
┌─────────────────────────────────────────────────────────┐
│                     CMS / PLATAFORMA                    │
│  WordPress / Ghost / Webflow / Contentful / Sanity      │
└─────────────────────────────────────────────────────────┘

---

Casos de uso

Processar um canal do YouTube em lote

Cada chave de API está limitada a 10 requisições por minuto. Como cada requisição fica aberta até o artigo ficar pronto, poucas requisições em paralelo são mais que suficientes:

async function processVideos(urls, { language = 'pt', concurrency = 2 } = {}) {
  const results = [];
  const queue = [...urls];

  async function worker() {
    while (queue.length > 0) {
      const url = queue.shift();
      try {
        results.push({ url, article: await generateArticle(url, language) });
      } catch (error) {
        if (error.status === 429 && error.retryAfter) {
          await new Promise((r) => setTimeout(r, error.retryAfter * 1000));
          queue.push(url); // tentar de novo mais tarde
        } else {
          results.push({ url, error: error.message });
        }
      }
    }
  }

  await Promise.all(Array.from({ length: concurrency }, worker));
  return results;
}

Interrompa o lote quando receber um 402: seu saldo de créditos não é suficiente para o próximo vídeo.

Publicar no WordPress

O Vidiome retorna seções, não HTML, então converta-as primeiro. Uma biblioteca de Markdown como marked resolve, ou você pode manter a conversão mínima:

import { marked } from 'marked';

async function publishToWordPress(article, { siteUrl, username, appPassword }) {
  const credentials = Buffer.from(`${username}:${appPassword}`).toString('base64');
  const html = marked.parse(
    article.sections.map((s) => `## ${s.title}\n\n${s.content}`).join('\n\n')
  );

  const response = await fetch(`${siteUrl}/wp-json/wp/v2/posts`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${credentials}`,
    },
    body: JSON.stringify({
      title: article.title,
      content: html,
      status: 'draft', // revisar antes de publicar
    }),
  });

  return response.json();
}

Um vídeo, vários idiomas

Faça uma requisição por idioma. Cada uma é uma geração independente e consome créditos como qualquer outra:

const LANGUAGES = ['en', 'fr', 'es', 'de'];

async function generateInLanguages(youtubeUrl) {
  const versions = {};
  for (const language of LANGUAGES) {
    versions[language] = await generateArticle(youtubeUrl, language);
  }
  return versions;
}

---

Limites e créditos

• Limite de taxa: 10 requisições por minuto por chave de API, em todos os planos pagos. Acima disso, você recebe 429 com um cabeçalho Retry-After (em segundos).
• Duração: cada requisição pode durar até 5 minutos do lado do Vidiome. Vídeos muito longos podem não caber nesse tempo; divida seu fluxo ou use o aplicativo web para eles.
• Créditos: a API custa o mesmo que o aplicativo web, à taxa atual de 4 créditos por minuto de vídeo, com mínimo de 20 créditos (um vídeo de 10 minutos consome 40 créditos; um de 60 minutos, 240). Cada resposta informa creditsUsed e creditsRemaining. Veja os preços para conhecer os planos e pacotes de créditos.

---

Tratamento de erros

Os erros são retornados em JSON com um campo error.

Status	error	O que fazer
400	Invalid request body ou invalid-youtube-url	Verifique a URL e o código de idioma
401	Missing API key / Invalid or revoked API key	Verifique o cabeçalho x-api-key
402	insufficient-credits (com required e available)	Recarregue créditos ou faça upgrade do plano
403	api_access_requires_paid_plan	Mude para um plano pago
404	no-captions	O vídeo não tem transcrição; tente outro vídeo
429	limite de taxa, ou transcript_provider_rate_limited	Aguarde o Retry-After e tente de novo
500	article_generation_failed	Tente de novo uma vez; se continuar falhando, fale conosco
502	transcript_provider_unavailable / llm_provider_error	Temporário: tente de novo após uma pausa

---

Perguntas frequentes

Posso enviar um arquivo de vídeo em vez de uma URL do YouTube?

Não. A API aceita apenas URLs do YouTube, e o vídeo precisa ter transcrição. Para arquivos MP4, MOV ou WebM, use o aplicativo web: ele transcreve o áudio e ainda captura uma imagem para cada seção.

Existe um webhook ou um endpoint de status?

Não. A requisição é síncrona e retorna o artigo pronto. Se você processa muitos vídeos, coloque as chamadas na sua própria fila de tarefas (um cron job, n8n, Make.com, um worker) e salve os resultados à medida que chegam.

Para onde vão os artigos gerados pela API?

Eles são salvos na sua conta Vidiome, então você os encontra no seu painel. É a forma mais simples de adicionar capturas de tela, corrigir um trecho com a reescrita por IA ou exportar o artigo em HTML ou Markdown.

---

Próximos passos

• Converta vídeos do YouTube manualmente pelo aplicativo web →
• Transforme um webinar em 5 artigos →
• Experimente o Vidiome grátis — 120 créditos, sem cartão →