Guia de mídia gerada com IA

Os tipos de mídia que a API gera ou processa, os campos de cada um, o ciclo de um job e os códigos de erro.

Uma geração é um job assíncrono: você pede com POST /media/generations, recebe 202 com o job e acompanha por GET /media/generations/{id} até done ou failed. O resultado entra na biblioteca de mídia do workspace (menos o do proxy), e o job pronto traz mediaId e mediaUrl.

As rotas estão no grupo Mídia gerada com IA da Referência da API.

Rotas

Método e caminhoPara que serve
GET /media/models?kind=Modelos que geram o tipo pedido (image, music, voice ou sfx). default marca o recomendado.
POST /media/generationsColoca uma geração na fila. Responde 202 com o job.
GET /media/generations/{id}Estado do job.

Tipos

O campo kind escolhe o tipo. Os quatro primeiros usam um modelo de IA e são cobrados do saldo; os outros são montados ou processados pela plataforma e não aceitam model.

kindO que fazResultado na biblioteca
imageGera uma imagem a partir do prompt, com imagens de referência opcionais.Imagem JPG
musicGera uma música (clipes de cerca de 30 s).Áudio M4A
voiceGera uma locução do roteiro exato em prompt.Áudio M4A
sfxGera um efeito sonoro com a duração pedida.Áudio M4A
videoMonta um vídeo a partir de uma linha do tempo.Vídeo MP4
cutoutRemove o fundo de uma imagem.Imagem PNG transparente
captionsGera legendas da fala de um áudio ou vídeo.Legendas WebVTT
denoiseLimpa o áudio de um áudio ou vídeo.Áudio M4A
proxyFaz uma cópia de edição de um vídeo (até 720p).Fora da biblioteca; uma cópia pronta da mesma origem é devolvida de novo sem reprocessar.

Campos por tipo

kindCamposRegras
imagemodel, prompt, aspect, referenceMediaIdsprompt até 4000 caracteres. Até 16 referências, sem vazias nem repetidas, todas imagens da biblioteca.
musicmodel, promptprompt até 2000 caracteres.
voicemodel, prompt, voiceprompt (o roteiro) até 1500 caracteres. voice é opcional: letras minúsculas, dígitos, _ e -, até 32 caracteres.
sfxmodel, prompt, durationMsprompt até 1000 caracteres. durationMs obrigatório, de 500 a 22000.
videoaspect, videoLinha do tempo descrita abaixo.
cutoutsourceMediaIdUma imagem da biblioteca.
captions, denoisesourceMediaIdUm áudio ou vídeo da biblioteca.
proxysourceMediaIdUm vídeo da biblioteca.

model é obrigatório em image, music, voice e sfx e precisa ser um id devolvido por GET /media/models para o mesmo tipo. Nos outros tipos, enviar model é recusado com unexpected.

aspect aceita:

ValorTamanho
square1080 x 1080
portrait1080 x 1350
story1080 x 1920
landscape1920 x 1080

Linha do tempo do vídeo

CampoRegra
video.durationMsDe 100 a 90000.
video.backgroundCor #rrggbb.
video.visualDe 1 a 8 faixas, de baixo para cima.
video.audioAté 6 faixas.
ClipesDe 1 a 80 no total. Os clipes de uma faixa não se sobrepõem.

Cada clipe:

CampoRegra
mediaIdObrigatório. Nas faixas visuais, uma imagem ou vídeo da biblioteca; nas de áudio, um áudio ou vídeo.
startMs, durationMs, trimInMsstartMs e trimInMs a partir de 0; durationMs de pelo menos 100; o clipe termina até video.durationMs.
volumeDe 0 a 2.
fadeInMs, fadeOutMsA partir de 0, somando no máximo a duração do clipe.
fitSó nas faixas visuais: cover ou contain.
transformSó nas faixas visuais: x, y (centro) e opacity de 0 a 1, w e h maiores que 0 e até 4, rotation de -360 a 360.
motionIn, motionOutSó nas faixas visuais e opcionais: edge (left, right, top ou bottom) e durationMs de pelo menos 100; as duas somam no máximo a duração do clipe.
keyframesSó nas faixas visuais e opcional; até 400 chaves na linha do tempo inteira.

Exemplos

Música:

{
  "kind": "music",
  "model": "google/lyria-3-clip-preview",
  "prompt": "Samba leve e acústico para o anúncio de uma cafeteria"
}

Vídeo de duas cenas com trilha:

{
  "kind": "video",
  "aspect": "story",
  "video": {
    "durationMs": 6000,
    "background": "#000000",
    "visual": [
      {
        "clips": [
          {
            "mediaId": "9d2f6a1e-3b4c-4d5e-8f70-1a2b3c4d5e6f",
            "startMs": 0,
            "durationMs": 3000,
            "trimInMs": 0,
            "fit": "cover",
            "transform": { "x": 0.5, "y": 0.5, "w": 1, "h": 1, "rotation": 0, "opacity": 1 },
            "volume": 0,
            "fadeInMs": 0,
            "fadeOutMs": 0
          },
          {
            "mediaId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "startMs": 3000,
            "durationMs": 3000,
            "trimInMs": 0,
            "fit": "contain",
            "transform": { "x": 0.5, "y": 0.5, "w": 1, "h": 1, "rotation": 0, "opacity": 1 },
            "volume": 0,
            "fadeInMs": 0,
            "fadeOutMs": 500,
            "motionIn": { "edge": "left", "durationMs": 400 }
          }
        ]
      }
    ],
    "audio": [
      {
        "clips": [
          {
            "mediaId": "7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b",
            "startMs": 0,
            "durationMs": 6000,
            "trimInMs": 0,
            "volume": 0.8,
            "fadeInMs": 0,
            "fadeOutMs": 1500
          }
        ]
      }
    ]
  }
}

Ciclo do job

statusSignificado
queuedNa fila.
runningEm andamento.
settlingPronto, aguardando o provedor informar o custo. O resultado só é entregue depois de cobrado.
donePronto, com mediaId, mediaUrl e model.
failedFalhou, com failureCode: generation_failed, storage_failed, timed_out, enqueue_failed, insufficient_funds, reference_unavailable, cost_unreported ou provider_busy.

Imagem, música, locução e efeito sonoro são cobrados do saldo pelo custo informado pelo provedor. Um pedido igual do mesmo usuário ainda em andamento devolve o mesmo job, sem nova cobrança.

Cada workspace tem no máximo 3 gerações com modelo (image, music, voice, sfx) e 2 processamentos (video, cutout, captions, denoise, proxy) em andamento ao mesmo tempo.

Erros

Campos inválidos respondem 422 invalid_request, com o código de cada campo em expected:

{
  "error": true,
  "code": "invalid_request",
  "message": "Há campos a corrigir",
  "expected": { "durationMs": "out_of_range", "model": "required" }
}

Os campos possíveis em expected são kind, model, prompt, aspect, referenceMediaIds, voice, durationMs, video.timeline e sourceMediaId, e os códigos são required, too_long, unknown, too_many, duplicate, not_found, not_image, wrong_type, out_of_range, unexpected e overlap.

CódigoStatusQuando
invalid_request422Há campos a corrigir.
too_many_jobs429O limite de jobs em andamento do tipo foi atingido.
insufficient_balance402Saldo insuficiente.
no_subscription402O workspace não tem uma assinatura ativa.
models_unavailable503A lista de modelos não pôde ser carregada; nada desse tipo pode ser pedido.
already_generating409O mesmo pedido acabou de ser feito.
not_found404O job não existe no workspace.