Endpoint

Autentique a solicitação com a API key disponível em Ajustes > Credenciais.

Authorization: Bearer $STREAM_TOOLS_API_KEY
Content-Type: application/json

Parâmetros

Exemplo com cURL

curl --request POST \
  --url https://api.stream.goinnovation.ai/v1/player/credentials \
  --header "Authorization: Bearer $STREAM_TOOLS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "resourceType": "channel",
    "resourceID": "11111111-2222-4333-8444-555555555555",
    "expiresInSeconds": 3600
  }'

Exemplo em Node.js

const response = await fetch(
  'https://api.stream.goinnovation.ai/v1/player/credentials',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.STREAM_TOOLS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      resourceType: 'channel',
      resourceID: '11111111-2222-4333-8444-555555555555',
      expiresInSeconds: 3600,
    }),
  },
)

if (!response.ok) {
  throw new Error(`Falha ao gerar credencial: ${response.status}`)
}

const { data } = await response.json()

Resposta

{
  "ok": true,
  "data": {
    "resourceType": "channel",
    "resourceID": "11111111-2222-4333-8444-555555555555",
    "playerKey": "eyJhbGciOi...exemplo",
    "playbackURL": "https://stream.goinnovation.ai/hls/channels/11111111-2222-4333-8444-555555555555/master.m3u8?token=eyJhbGciOi...exemplo",
    "issuedAt": "2026-07-27T18:00:00.000Z",
    "expiresAt": "2026-07-27T19:00:00.000Z",
    "renewAfter": "2026-07-27T18:48:00.000Z"
  }
}

Renovação sem interrupção

1. Guarde a API key somente no backend da sua aplicação.
2. Solicite uma credencial antes de iniciar o player.
3. Agende a próxima solicitação para o instante indicado em renewAfter.
4. Atualize a URL HLS do player antes de expiresAt.

Para uma rotina a cada 24 horas, use uma validade maior que o intervalo, como 172800 segundos, para preservar uma margem segura caso uma renovação atrase. A validade máxima é de sete dias.

Rotação de segurança

A rotação da chave do player feita em Ajustes > Credenciais faz com que novas solicitações com credenciais temporárias anteriores sejam recusadas. Conexões já abertas podem concluir os pequenos grants de mídia emitidos antes da rotação. Gere uma nova credencial por esta rota.

Erros

Dashboard

Sem filtros, retorna os últimos sete dias. start e end usam Unix time em segundos e aceitam períodos de até dois anos.

curl --get \
  --url https://api.stream.goinnovation.ai/v1/analytics/dashboard \
  --header "Authorization: Bearer $STREAM_TOOLS_API_KEY" \
  --data-urlencode "grain=day" \
  --data-urlencode "resourceType=channel" \
  --data-urlencode "resourceID=11111111-2222-4333-8444-555555555555"

A resposta contém overview, timeline, audiência por canal, tráfego HLS/DASH/SRT, recursos, dimensões geográficas e técnicas, unavailableSections e o instante de retenção detalhada em detailAvailableFrom.

Recursos disponíveis

Lista conteúdos, playlists e canais da conta para montar seletores antes de consultar métricas por recurso.

curl \
  --url https://api.stream.goinnovation.ai/v1/analytics/resources \
  --header "Authorization: Bearer $STREAM_TOOLS_API_KEY"

Exportação CSV

Aceita os mesmos filtros do dashboard e devolve um CSV UTF-8 com resumo, séries temporais, recursos, protocolos e segmentações.

curl --get \
  --url https://api.stream.goinnovation.ai/v1/analytics/export.csv \
  --header "Authorization: Bearer $STREAM_TOOLS_API_KEY" \
  --data-urlencode "grain=day" \
  --output gostream-analytics.csv

Erros de Analytics

Visão geral

1. Liste os recursos que podem receber campanhas.
2. Envie a imagem original e guarde o ID da mídia pronta.
3. Crie a campanha com agenda, frequência, alvos e pesos.
4. Seu backend cria uma sessão para a origem HTTPS exata da página.
5. O SDK posiciona a camada HTML sem reparentar nem alterar o vídeo.
6. Consulte impressões, cliques, duração visível e encerramentos.

O contrato completo e legível por ferramentas está em /openapi.json.

Autenticação

Use X-API-Key no backend. Authorization: Bearer continua aceito para integrações existentes. Toda resposta de erro possui code estável; guarde também o request ID retornado para suporte.

curl https://api.stream.goinnovation.ai/v1/pause-ads/resources \
  --header "X-API-Key: $STREAM_TOOLS_API_KEY"

Permissões: leitura usa content.view; criação e edição usam content.upload; relatórios usam analytics.view; sessões usam settings.credentials.

Recursos

Retorna somente conteúdos, playlists e canais da conta. Filtre por type, status e search. Listagens usam limit de 1 a 100 e um cursor opaco; reutilize nextCursor sem modificá-lo.

Mídias

Envie apenas o arquivo original JPEG, PNG ou WebP em multipart/form-data. Ele deve ter proporção 16:9, pelo menos 1280×720 e no máximo 15 MiB. O GoStream gera o WebP 1280×720 de entrega; não envie uma segunda versão otimizada.

curl --request POST \
  --url https://api.stream.goinnovation.ai/v1/pause-ads/creatives \
  --header "X-API-Key: $STREAM_TOOLS_API_KEY" \
  --header "Idempotency-Key: creative-launch-2026-08" \
  --form "original=@pause-ad.png;type=image/png" \
  --form "name=Campanha institucional" \
  --form "altText=Conheça nossa programação" \
  --form "destinationURL=https://customer.example/campanha" \
  --form "fitMode=contain"

Criações exigem Idempotency-Key de 8 a 128 caracteres. A mesma requisição pode ser repetida por 24 horas; reutilizar a chave com outro corpo retorna 409 IDEMPOTENCY_CONFLICT.

Campanhas

Campanhas definem agenda, timezone, prioridade, tempo mínimo, fechamento, cooldown, limite por sessão, pesos das mídias e alvos. Uma campanha ACTIVE precisa ter ao menos uma mídia pronta e um alvo da conta.

{
  "name": "Intervalo institucional",
  "status": "ACTIVE",
  "priority": 100,
  "startsAt": "2026-08-28T00:00:00.000Z",
  "endsAt": "2026-09-30T23:59:59.000Z",
  "timezone": "America/Sao_Paulo",
  "minWatchSeconds": 2,
  "cooldownSeconds": 300,
  "sessionCap": 3,
  "closeAfterSeconds": 15,
  "creatives": [{ "creativeID": "UUID-DA-MIDIA", "weight": 1 }],
  "targets": [{ "resourceType": "channel", "resourceID": "UUID-DO-CANAL" }]
}

Use GET /campaigns, GET /campaigns/{campaignID}, PATCH /campaigns/{campaignID} e DELETE /campaigns/{campaignID} para o ciclo completo.

Sessões do navegador

Esta chamada acontece no seu backend. embedDomain é a origem HTTPS exata da página, inclusive porta não padrão. A resposta dura 15 minutos e pode ser devolvida ao navegador; ela não contém a API key.

app.post('/pause-ads/session', async (request, response) => {
  const upstream = await fetch(
    'https://api.stream.goinnovation.ai/v1/pause-ads/sessions',
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.STREAM_TOOLS_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        resourceType: 'channel',
        resourceID: request.body.resourceID,
        embedDomain: 'https://player.customer.example',
      }),
    },
  )
  const payload = await upstream.json()
  response.status(upstream.status).json(payload.data ?? payload)
})

Use a opção locale do SDK: pt-BR (padrão), en ou es. Ela traduz rótulos, acessibilidade e contagem regressiva; o texto da campanha é preservado.

SDK e HTML

A versão do módulo oficial com suporte a idiomas está em https://docs.stream.goinnovation.ai/sdk/pause-ads-v1.js?v=20260918-i18n. O container deve conter o vídeo e ter o mesmo tamanho visual do player. O SDK adiciona apenas uma camada irmã; ele não envolve o vídeo, não chama pause() e não troca src.

<div class="player-shell">
  <video id="stream" controls playsinline></video>
</div>
<style>
  .player-shell { position: relative; aspect-ratio: 16 / 9; background: #000; }
  .player-shell video { display: block; width: 100%; height: 100%; }
</style>

import { mountPauseAds } from
  'https://docs.stream.goinnovation.ai/sdk/pause-ads-v1.js?v=20260918-i18n'

const sessionResponse = await fetch('/pause-ads/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ resourceID: 'UUID-DO-CANAL' }),
})
const session = await sessionResponse.json()
const pauseAds = await mountPauseAds({
  container: document.querySelector('.player-shell'),
  media: document.querySelector('#stream'),
  locale: 'pt-BR',
  session,
})

// Ao remover o player:
pauseAds.destroy()

A camada aparece apenas depois de uma pausa deliberada e estável. O X e o timeout mantêm o vídeo pausado; a reprodução volta somente pelo Play do próprio player. Em fullscreen nativo do elemento video, o navegador pode impedir overlays; prefira colocar o container em fullscreen.

Video.js

const player = videojs('stream')
const pauseAds = await mountPauseAds({
  container: player.el(),
  media: player.el().querySelector('video'),
  session,
  isAdBreakActive: () => player.ads?.isInAdMode?.() ?? false,
})
player.on('dispose', () => pauseAds.destroy())

HLS.js

const media = document.querySelector('#stream')
const hls = new Hls()
hls.loadSource(playbackURL)
hls.attachMedia(media)
const pauseAds = await mountPauseAds({
  container: media.parentElement,
  media,
  session,
})
hls.on(Hls.Events.DESTROYING, () => pauseAds.destroy())

Shaka Player

const media = document.querySelector('#stream')
const player = new shaka.Player(media)
await player.load(playbackURL)
const pauseAds = await mountPauseAds({
  container: media.parentElement,
  media,
  session,
})
player.addEventListener('unloading', () => pauseAds.destroy())

Google IMA

Informe o estado do intervalo linear para nunca sobrepor Pause Ads ao anúncio. A callback também funciona com videojs-ima e outros gerenciadores.

let imaActive = false
const pauseAds = await mountPauseAds({
  container,
  media,
  session,
  isAdBreakActive: () => imaActive,
})
adsManager.addEventListener('CONTENT_PAUSE_REQUESTED', () => {
  imaActive = true
  pauseAds.setAdBreakActive(true)
})
adsManager.addEventListener('CONTENT_RESUME_REQUESTED', () => {
  imaActive = false
  pauseAds.setAdBreakActive(false)
})

Eventos

Tokens permanecem apenas em memória; o SDK não usa cookies, localStorage ou IndexedDB.

Relatórios e CSV

Filtre por start, end, resourceType, resourceID, campaignID e creativeID. O JSON retorna resumo, série, campanhas e mídias com impressões, sessões únicas, cliques, CTR, duração visível média, fechamentos, retomadas, no-fill e erros. A série é horária para até dois dias e diária nos períodos maiores, com limite máximo de 89 dias.

curl --get \
  --url https://api.stream.goinnovation.ai/v1/pause-ads/reports/export.csv \
  --header "X-API-Key: $STREAM_TOOLS_API_KEY" \
  --data-urlencode "start=2026-08-01" \
  --data-urlencode "end=2026-08-28" \
  --output pause-ads.csv

Erros

Rate limits

Por API key: 600 leituras a cada 10 minutos; 120 mutações por hora; 30 uploads por hora; 120 relatórios por hora; e 6000 sessões a cada 10 minutos. Um 429 informa o tempo real em Retry-After.

Solução de problemas

• Sem overlay: confirme campanha ativa, alvo, agenda, cooldown e limite da sessão.
• 401/403 no config: a origem deve coincidir exatamente com embedDomain e estar autorizada.
• Imagem bloqueada: permita https://stream.goinnovation.ai em img-src e connect-src.
• SDK bloqueado: permita https://docs.stream.goinnovation.ai em script-src e style-src.
• Fullscreen: solicite fullscreen no container do player, não diretamente no vídeo.
• Troca de fonte: destrua o controller ao descartar o player; uma nova montagem cria estado limpo.