Para desenvolvedores

    API do ViralRecast

    Os olhos e ouvidos das redes sociais, orgânicas e pagas, dentro do seu código. Leia qualquer post, descubra o que está em alta, espione anúncios de concorrentes e gere cortes, com as mesmas ferramentas que o Claude e o ChatGPT usam.

    POSThttps://viralrecast.com/mcp

    Começo rápido

    É um endpoint só. Você manda um POST com JSON-RPC 2.0 dizendo qual ferramenta quer usar e com quais argumentos, e recebe o resultado em JSON. Não tem SDK para instalar.

    1. 1. Pegue sua chave

      Entre na sua conta e copie a chave em viralrecast.com/connect. Ela começa com vr_. Toda conta nova ganha créditos grátis para testar.

      bash
      export VIRALRECAST_KEY="vr_..."
    2. 2. Liste as ferramentas (grátis)

      bash
      curl -s https://viralrecast.com/mcp \
        -H "Authorization: Bearer $VIRALRECAST_KEY" \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
        | jq '.result.tools[].name'
    3. 3. Leia um post

      bash
      curl -s https://viralrecast.com/mcp \
        -H "Authorization: Bearer $VIRALRECAST_KEY" \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_post","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","include_images":false}}}' \
        | jq '.result.structuredContent'

    Autenticação

    Mande a chave no cabeçalho Authorization: Bearer vr_... (ou em X-API-Key: vr_...). Cada chamada é cobrada dos créditos da conta dona da chave.

    • • A chave dá acesso aos seus créditos. Guarde no servidor (variável de ambiente), nunca no front-end ou num repositório público.
    • • Vazou? Gere outra em /connect. A antiga para de funcionar na hora.
    • • Apps que conectam contas de outras pessoas (como o Claude e o ChatGPT) usam OAuth 2.1 com descoberta automática, em vez da chave.

    Requisição e resposta

    Para rodar uma ferramenta, use o método tools/call:

    request
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "search_viral_content",
        "arguments": { "query": "receitas fit", "platforms": ["tiktok"], "region": "BR" }
      }
    }

    O resultado vem em result.structuredContent (JSON pronto para usar). O mesmo conteúdo vem como texto em result.content[0].text, que é o que os assistentes de IA leem. Toda resposta cobrada traz credits_charged.

    response
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [{ "type": "text", "text": "{ ...o mesmo JSON... }" }],
        "structuredContent": { "query": "receitas fit", "results": [ ... ], "credits_charged": 4 }
      }
    }

    Também funcionam: tools/list (ferramentas e o schema de cada uma), initialize, ping e lotes (um array de mensagens num POST só). O endpoint é o servidor MCP do ViralRecast (Streamable HTTP, sem stream SSE): qualquer cliente MCP fala com ele sem adaptação.

    Conteúdo orgânico

    read_post

    Custa 20 créditos (2 se o post já foi lido nas últimas 6 horas).

    Lê qualquer post pelo link (TikTok, Instagram reel/carrossel/foto, YouTube, X, Threads, LinkedIn, Reddit) e devolve o conteúdo inteiro para você analisar: transcrição com tempos (da própria rede ou, se ela não legendou, transcrição automática do áudio), as imagens do carrossel (como imagens, para você ver) e o texto escrito em cada slide, comentários mais curtidos, métricas, resumo, pontos-chave, mapa mental e o Viral Score (quão fora da curva o post foi para o tamanho do autor). Use sempre que o usuário colar um link ou pedir para resumir, entender, estudar ou comparar um post. Grava no histórico do usuário.

    ParâmetroDescrição
    urlobrigatóriostring

    Link do post

    nichestring

    Tema/nicho de referência do usuário, para a nota de encaixe (fit)

    include_imagesboolean

    Devolver as imagens do carrossel (padrão true)

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_post","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","include_images":false}}}' \
      | jq '.result.structuredContent'
    Ver exemplo de resposta (structuredContent, encurtado)
    json
    {
      "id": 73,
      "platform": "youtube",
      "format": "video",
      "url": "https://www.youtube.com/watch?v=KvLWuK2TU-w",
      "author": { "handle": "HTXStudio", "name": "HTX Studio", "followers": 2830000 },
      "title": "We Built the Product Apple Gave Up On...",
      "duration_s": 325,
      "published_at": "2026-09-24T12:00:31Z",
      "metrics": { "views": 5939233, "likes": 95213, "comments": 3400, "shares": 0, "saves": 0 },
      "slides": [],
      "transcript": [
        { "start": 0.2, "end": 4, "text": "For the past 2 months, I have been" },
        { "start": 2.1, "end": 6.3, "text": "building a desk. To understand what it" }
      ],
      "transcript_text": "For the past 2 months, I have been building a desk...",
      "transcript_source": "platform",
      "top_comments": [{ "text": "2027 Apple Airdesk - Starting At $99,999", "likes": 8700, "author": "@..." }],
      "analysis": {
        "hook": "...", "summary": "...", "key_points": ["..."], "mind_map": "# ...",
        "pattern": "história", "emotion": "admiração", "hook_score": 8,
        "why_it_worked": "...", "how_to_adapt": ["..."]
      },
      "score": { "viral_index": 100, "tier": "fora_da_curva", "outlier": 31.31, "final_score": 21.92 },
      "from_memory": true,
      "credits_charged": 2,
      "dashboard_url": "https://viralrecast.com/p/73"
    }

    my_history

    Grátis.

    As consultas recentes do usuário no ViralRecast (painel, Claude, ChatGPT), com o Viral Score de cada post.

    ParâmetroDescrição
    limitinteger

    Quantas (padrão 15)

    Intervalo: 1 a 50

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"my_history","arguments":{"limit":10}}}' \
      | jq '.result.structuredContent'

    similar_content

    Custa 1 crédito.

    Conteúdos parecidos com um post já lido, na memória coletiva do ViralRecast (tudo o que já foi consultado na plataforma). Informe o content_id devolvido por read_post.

    ParâmetroDescrição
    content_idobrigatóriointeger

    id do conteúdo (campo id de read_post)

    limitinteger

    Intervalo: 1 a 20

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"similar_content","arguments":{"content_id":73,"limit":5}}}' \
      | jq '.result.structuredContent'

    search_viral_content

    Custa 4 créditos por rede; instagram_carousel custa 100 (descobre autores pela hashtag e lê a grade deles).

    Busca posts em alta sobre um tema e ranqueia pelo trend_score (alcance + engajamento + viralidade relativa ao tamanho do criador). Redes: tiktok, instagram (Reels), youtube, x, threads, reddit e instagram_carousel (carrosséis e fotos do Instagram). Sem platforms busca em tiktok, instagram, youtube e x. Use instagram_carousel quando o usuário pedir carrossel/foto, reddit ou threads quando pedir discussão/texto.

    ParâmetroDescrição
    queryobrigatóriostring

    Tema ou palavra-chave, ex.: "marketing para dentistas"

    platformsstring[]

    Redes (padrão: tiktok, instagram, youtube, x)

    tiktokinstagramyoutubexthreadsredditinstagram_carousel

    periodstring

    Janela de tempo (padrão week)

    dayweekmonthall

    limitinteger

    Máximo de resultados (padrão 10)

    Intervalo: 1 a 30

    regionstring

    País, ISO-3166 (BR, US, PT...): filtra o TikTok por país e o X por idioma (BR = português). Omita para global. Use BR quando o usuário falar português e quiser o mercado brasileiro

    min_followersinteger

    Só criadores com pelo menos N seguidores

    Intervalo: 0+

    max_followersinteger

    Só criadores com até N seguidores. Use quando o usuário pedir perfis pequenos, micro-criadores ou prospecção (ex.: 10000). Os resultados trazem author.followers verificado; não chame analyze_creator só para conferir seguidores.

    Intervalo: 1+

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_viral_content","arguments":{"query":"receitas fit","platforms":["tiktok","instagram"],"region":"BR","limit":10}}}' \
      | jq '.result.structuredContent'
    Ver exemplo de resposta (structuredContent, encurtado)
    json
    {
      "query": "receitas fit",
      "period": "week",
      "region": "BR",
      "platforms": ["tiktok"],
      "results": [
        {
          "platform": "tiktok",
          "url": "https://www.tiktok.com/@cacau.stadler/video/7688130098309991687",
          "text": "BOLO DE LIMÃO FIT...",
          "is_video": true,
          "duration": 122.8,
          "published_at": "2026-09-21T23:11:30+00:00",
          "views": 341272, "likes": 16364, "comments": 243, "shares": 3966,
          "author": { "handle": "cacau.stadler", "name": "Cacau Stadler", "followers": 30665 },
          "trend_score": 70,
          "engagement_rate": 8.42,
          "views_per_follower": 11.13,
          "age_days": 6
        }
      ],
      "total_found": 4,
      "errors": null,
      "credits_charged": 4
    }

    analyze_creator

    Custa 8 créditos.

    Perfil de um criador com médias e os posts que mais furaram a bolha em relação à própria média.

    ParâmetroDescrição
    platformobrigatóriostring

    tiktokinstagramyoutubetwitter

    handleobrigatóriostring

    @ do criador, com ou sem @

    limitinteger

    Quantos posts devolver (padrão 12)

    Intervalo: 3 a 30

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze_creator","arguments":{"platform":"instagram","handle":"@nasa","limit":12}}}' \
      | jq '.result.structuredContent'

    find_similar_posts

    Custa 1 crédito.

    Busca por similaridade na base de posts virais já indexados. Útil para validar uma ideia de post.

    ParâmetroDescrição
    textobrigatóriostring

    Ideia, roteiro ou legenda

    platformstring
    limitinteger

    Intervalo: 1 a 20

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_similar_posts","arguments":{"text":"3 erros que todo iniciante comete na academia","limit":5}}}' \
      | jq '.result.structuredContent'

    analyze_post

    legadoCusta 20 créditos.

    Igual a read_post, mas sem as imagens (mantida por compatibilidade). Prefira read_post.

    ParâmetroDescrição
    urlobrigatóriostring

    Link do post (YouTube, TikTok, Instagram, X ou Facebook)

    nichestring

    Nicho do usuário, para as ideias de adaptação

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze_post","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w"}}}' \
      | jq '.result.structuredContent'

    Anúncios (mídia paga)

    search_ads

    Custa 4 créditos por rede.

    Anúncios ativos sobre um tema nas bibliotecas públicas do Meta (Facebook e Instagram), TikTok e LinkedIn: texto, título, CTA, página de destino, formato, onde roda, há quantos dias está no ar e quantas variações tem. Ordena pelos sinais de anúncio vencedor (quem paga não mantém no ar o que não converte: 30+ dias ou 3+ variações = forte). Use para 'o que está em alta nos anúncios de X', pesquisa de criativos e ofertas.

    ParâmetroDescrição
    queryobrigatóriostring

    Tema, produto ou palavra-chave, ex.: "curso de inglês", "skincare"

    platformsstring[]

    Padrão: meta

    metatiktoklinkedin

    countrystring

    País ISO-3166 (BR, US...) ou ALL. Padrão BR (vale para Meta e LinkedIn)

    mediastring

    Só Meta. Padrão ALL

    ALLVIDEOIMAGE

    limitinteger

    Intervalo: 1 a 40

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_ads","arguments":{"query":"curso de inglês","platforms":["meta"],"country":"BR","limit":10}}}' \
      | jq '.result.structuredContent'
    Ver exemplo de resposta (structuredContent, encurtado)
    json
    {
      "query": "curso de inglês",
      "country": "BR",
      "platforms": ["meta"],
      "ads": [
        {
          "platform": "meta",
          "url": "https://www.facebook.com/ads/library?id=688654197622766",
          "advertiser": "Professor Kenny",
          "active": true,
          "started_at": "2025-10-06T07:00:00+00:00",
          "days_running": 357,
          "variations": 12,
          "format": "video",
          "headline": "Curso de Inglês Prof Kenny",
          "text": "Vi que você quase iniciou o melhor curso de inglês do país...",
          "cta": "Learn more",
          "landing_url": "https://www.profkenny.com.br/...",
          "placements": ["facebook", "instagram"],
          "winner_signal": "forte"
        }
      ],
      "total_found": 27,
      "library_totals": { "meta": 7840 },
      "credits_charged": 4
    }

    advertiser_ads

    Custa 4 créditos por rede (Google pelo nome: 8).

    Todos os anúncios ativos de uma marca ou concorrente no Meta, Google (Pesquisa, YouTube, Display), LinkedIn e TikTok, com o resumo por rede: quantos anúncios, formatos e o mais antigo no ar. Aceita o nome da empresa ou o site (ex.: reportei.com).

    ParâmetroDescrição
    advertiserobrigatóriostring

    Nome da empresa/página ou domínio do site

    platformsstring[]

    Padrão: meta e google

    metagooglelinkedintiktok

    countrystring

    País ISO-3166 ou ALL. Padrão BR

    limitinteger

    Intervalo: 1 a 40

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"advertiser_ads","arguments":{"advertiser":"reportei.com","platforms":["meta","google"]}}}' \
      | jq '.result.structuredContent'

    read_ad

    Custa 10 créditos.

    Criativo completo de um anúncio pelo link da biblioteca (Meta: facebook.com/ads/library?id=...; Google: adstransparency.google.com; LinkedIn: linkedin.com/ad-library; TikTok: library.tiktok.com): textos de todas as versões, CTA, destino, dias no ar e a transcrição do vídeo (Meta). Use para destrinchar gancho, roteiro e oferta.

    ParâmetroDescrição
    urlobrigatóriostring

    Link do anúncio na biblioteca (ou o ID do anúncio do Meta)

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_ad","arguments":{"url":"https://www.facebook.com/ads/library?id=688654197622766"}}}' \
      | jq '.result.structuredContent'

    Vídeo: download, transcrição e cortes

    download_video

    Custa 10 créditos (estornados se falhar).

    Baixa o vídeo de um link (YouTube, TikTok sem marca d'água, Instagram, X, Facebook) e devolve um link de download. Use só para conteúdo próprio, licenciado ou para referência interna.

    ParâmetroDescrição
    urlobrigatóriostring
    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"download_video","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w"}}}' \
      | jq '.result.structuredContent'

    transcribe_video

    Custa 8 créditos + 4 por minuto de vídeo (estornados se falhar).

    Transcrição completa de um vídeo por link, com links de SRT/VTT.

    ParâmetroDescrição
    urlobrigatóriostring
    languagestring

    ISO-639-1; vazio = automático

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"transcribe_video","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","language":"en"}}}' \
      | jq '.result.structuredContent'

    create_clips

    Custa 100 créditos + 4 por minuto de vídeo, limite de 180 min (estornados se falhar).

    Transforma um vídeo longo em cortes verticais prontos para postar, com legenda, título, gancho e hashtags. Informe url OU job_id de um download já feito. Leva de 1 a 5 minutos: a tool devolve um job_id; consulte com get_job. Use em conteúdo próprio ou licenciado.

    ParâmetroDescrição
    urlstring
    job_idstring

    ID de um job de download concluído

    clip_countinteger

    Quantos cortes (padrão 5)

    Intervalo: 1 a 10

    min_secondsinteger

    Duração mínima de cada corte (padrão 20)

    Intervalo: 5 a 180

    max_secondsinteger

    Duração máxima de cada corte (padrão 60)

    Intervalo: 10 a 180

    orientationstring

    Formato de saída (padrão vertical 9:16)

    verticalhorizontalsquareoriginal

    captionsboolean

    Queimar legendas palavra por palavra (padrão true)

    languagestring

    Idioma do áudio, ISO-639-1 (pt, en, es). Vazio = automático

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_clips","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","clip_count":3,"orientation":"vertical"}}}' \
      | jq '.result.structuredContent'

    get_job

    Grátis.

    Status e resultado de um job de download, transcrição ou cortes.

    ParâmetroDescrição
    job_idobrigatóriostring
    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_job","arguments":{"job_id":"e8ab6df8-8456-4661-a285-fdd73f5ed504"}}}' \
      | jq '.result.structuredContent'
    Ver exemplo de resposta (structuredContent, encurtado)
    json
    {
      "id": "e8ab6df8-8456-4661-a285-fdd73f5ed504",
      "job_id": "e8ab6df8-8456-4661-a285-fdd73f5ed504",
      "type": "clips",
      "status": "completed",
      "progress": 100,
      "platform": "youtube",
      "credits_charged": 296,
      "duration_seconds": 2888,
      "refunded": false,
      "error": null,
      "source": { "url": "https://www.youtube.com/watch?v=MVYeIUoUMHY", "title": "...", "views": 162980, "duration": 2888 },
      "download": {
        "url": "https://viralrecast.com/files/e8ab6df8-.../7fdf2ec109642c3f0501/video.mp4",
        "width": 1920, "height": 1080, "duration": 2887.08, "size": 2109692276
      },
      "transcript": {
        "language": "Portuguese",
        "text": "...",
        "srt_url": "https://viralrecast.com/files/e8ab6df8-.../08a982d85d63b7db0ea3/transcript.srt",
        "vtt_url": "https://viralrecast.com/files/e8ab6df8-.../3f4ba6e141825d0ed8f6/transcript.vtt",
        "json_url": "https://viralrecast.com/files/e8ab6df8-.../916e3ab07b93c71cc1d3/transcript.json"
      },
      "clips": [
        {
          "index": 1,
          "url": "https://viralrecast.com/files/e8ab6df8-.../52efab45177cf1951257/clip-1.mp4",
          "thumbnail": "https://viralrecast.com/files/e8ab6df8-.../cca1d35b5d715999012b/clip-1.jpg",
          "start": 1184, "end": 1209, "duration": 25,
          "title": "...", "hook": "...", "description": "...",
          "hashtags": ["#humor", "#verao", "#piscina"],
          "score": 74,
          "reason": "...",
          "aspect": "9:16"
        }
      ]
    }

    list_jobs

    Grátis.

    Últimos jobs de mídia do usuário.

    ParâmetroDescrição
    limitinteger

    Intervalo: 1 a 50

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_jobs","arguments":{"limit":10}}}' \
      | jq '.result.structuredContent'

    Conta

    get_account

    Grátis.

    Plano, créditos restantes e a tabela de preço de cada tool.

    Sem parâmetros.

    bash
    curl -s https://viralrecast.com/mcp \
      -H "Authorization: Bearer $VIRALRECAST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}' \
      | jq '.result.structuredContent'

    Jobs e arquivos

    Download e transcrição costumam voltar prontos na mesma chamada. Cortes levam de 1 a 5 minutos: a chamada devolve um job_id com status queued ou processing. Consulte get_job a cada 20 ou 30 segundos até o status virar completed (ou failed, com estorno automático dos créditos).

    bash
    JOB=$(curl -s https://viralrecast.com/mcp -H "Authorization: Bearer $VIRALRECAST_KEY" -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_clips","arguments":{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","clip_count":3}}}' \
      | jq -r '.result.structuredContent.job_id')
    
    while true; do
      STATUS=$(curl -s https://viralrecast.com/mcp -H "Authorization: Bearer $VIRALRECAST_KEY" -H "Content-Type: application/json" \
        -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"get_job\",\"arguments\":{\"job_id\":\"$JOB\"}}}" \
        | jq -r '.result.structuredContent.status')
      echo "$STATUS"; [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
      sleep 20
    done

    Os arquivos gerados (vídeo, legendas, cortes e capas) vêm como links https://viralrecast.com/files/...:

    • • Abrem sem chave, então dá para usar direto numa tag <video> ou num player. Trate o link como privado: quem tiver o link consegue abrir o arquivo.
    • • Aceitam o cabeçalho Range (resposta 206), então o player consegue avançar e voltar o vídeo sem baixar tudo.
    • • Acrescente ?download=1 para forçar o download com nome de arquivo.
    bash
    curl -L -o corte-1.mp4 "https://viralrecast.com/files/<job>/<assinatura>/clip-1.mp4?download=1"

    Créditos e limites

    A API usa os mesmos créditos do painel e dos assistentes. A tabela abaixo sai da própria API, então está sempre com o preço vigente (a tool get_account devolve a mesma tabela). Planos em /pricing.

    ToolCréditos
    read_postCusta 20 créditos (2 se o post já foi lido nas últimas 6 horas).
    my_historyGrátis.
    similar_contentCusta 1 crédito.
    search_viral_contentCusta 4 créditos por rede; instagram_carousel custa 100 (descobre autores pela hashtag e lê a grade deles).
    trending_nowCusta 4 créditos.
    analyze_creatorCusta 8 créditos.
    find_similar_postsCusta 1 crédito.
    search_adsCusta 4 créditos por rede.
    advertiser_adsCusta 4 créditos por rede (Google pelo nome: 8).
    read_adCusta 10 créditos.
    download_videoCusta 10 créditos (estornados se falhar).
    transcribe_videoCusta 8 créditos + 4 por minuto de vídeo (estornados se falhar).
    create_clipsCusta 100 créditos + 4 por minuto de vídeo, limite de 180 min (estornados se falhar).
    get_jobGrátis.
    list_jobsGrátis.
    get_accountGrátis.
    • • Falhou? Não cobra: rede que não respondeu, post indisponível e job que falhou têm os créditos estornados.
    • • Limite de 120 chamadas por minuto por conta. Acima disso a resposta é HTTP 429; espere alguns segundos e tente de novo.
    • • Algumas chamadas buscam dados ao vivo em várias redes e levam até 60 segundos. Use timeout de 120 segundos no cliente.

    Erros

    RespostaO que significa
    HTTP 200 + result.isError: trueA ferramenta rodou e não conseguiu (créditos insuficientes, link inválido, post privado). A mensagem para mostrar ao usuário está em result.content[0].text.
    HTTP 401 invalid_tokenChave ausente, errada ou trocada.
    HTTP 429Muitas chamadas por minuto.
    HTTP 405Use POST.
    error.code -32700O corpo não é um JSON válido.
    error.code -32601Método JSON-RPC não suportado.
    error.code -32603Erro interno. Tente de novo; se continuar, fale com o suporte.
    exemplo: créditos insuficientes
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [{ "type": "text", "text": "Créditos insuficientes: esta tool custa 4 e restam 2. Faça upgrade em https://viralrecast.com/pricing" }],
        "isError": true
      }
    }

    Claude, ChatGPT e agentes

    Como a API é um servidor MCP, ela entra direto no Claude, no ChatGPT, no Cursor e em qualquer agente compatível com MCP. O passo a passo de cada um está em /connect.

    Claude Code
    claude mcp add --transport http viralrecast https://viralrecast.com/mcp --header "Authorization: Bearer $VIRALRECAST_KEY"
    Cursor e outros clientes MCP
    {
      "mcpServers": {
        "viralrecast": {
          "url": "https://viralrecast.com/mcp",
          "headers": { "Authorization": "Bearer vr_..." }
        }
      }
    }

    Pronto para testar?

    Crie a conta com Google, pegue a chave e faça a primeira chamada com os créditos grátis.

    Use download e cortes só em conteúdo próprio ou licenciado. Veja os Termos de uso.