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 caminho | Para que serve |
|---|---|
GET /media/models?kind= | Modelos que geram o tipo pedido (image, music, voice ou sfx). default marca o recomendado. |
POST /media/generations | Coloca 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.
kind | O que faz | Resultado na biblioteca |
|---|---|---|
image | Gera uma imagem a partir do prompt, com imagens de referência opcionais. | Imagem JPG |
music | Gera uma música (clipes de cerca de 30 s). | Áudio M4A |
voice | Gera uma locução do roteiro exato em prompt. | Áudio M4A |
sfx | Gera um efeito sonoro com a duração pedida. | Áudio M4A |
video | Monta um vídeo a partir de uma linha do tempo. | Vídeo MP4 |
cutout | Remove o fundo de uma imagem. | Imagem PNG transparente |
captions | Gera legendas da fala de um áudio ou vídeo. | Legendas WebVTT |
denoise | Limpa o áudio de um áudio ou vídeo. | Áudio M4A |
proxy | Faz 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
kind | Campos | Regras |
|---|---|---|
image | model, prompt, aspect, referenceMediaIds | prompt até 4000 caracteres. Até 16 referências, sem vazias nem repetidas, todas imagens da biblioteca. |
music | model, prompt | prompt até 2000 caracteres. |
voice | model, prompt, voice | prompt (o roteiro) até 1500 caracteres. voice é opcional: letras minúsculas, dígitos, _ e -, até 32 caracteres. |
sfx | model, prompt, durationMs | prompt até 1000 caracteres. durationMs obrigatório, de 500 a 22000. |
video | aspect, video | Linha do tempo descrita abaixo. |
cutout | sourceMediaId | Uma imagem da biblioteca. |
captions, denoise | sourceMediaId | Um áudio ou vídeo da biblioteca. |
proxy | sourceMediaId | Um 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:
| Valor | Tamanho |
|---|---|
square | 1080 x 1080 |
portrait | 1080 x 1350 |
story | 1080 x 1920 |
landscape | 1920 x 1080 |
Linha do tempo do vídeo
| Campo | Regra |
|---|---|
video.durationMs | De 100 a 90000. |
video.background | Cor #rrggbb. |
video.visual | De 1 a 8 faixas, de baixo para cima. |
video.audio | Até 6 faixas. |
| Clipes | De 1 a 80 no total. Os clipes de uma faixa não se sobrepõem. |
Cada clipe:
| Campo | Regra |
|---|---|
mediaId | Obrigatório. Nas faixas visuais, uma imagem ou vídeo da biblioteca; nas de áudio, um áudio ou vídeo. |
startMs, durationMs, trimInMs | startMs e trimInMs a partir de 0; durationMs de pelo menos 100; o clipe termina até video.durationMs. |
volume | De 0 a 2. |
fadeInMs, fadeOutMs | A partir de 0, somando no máximo a duração do clipe. |
fit | Só nas faixas visuais: cover ou contain. |
transform | Só 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, motionOut | Só 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. |
keyframes | Só 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
status | Significado |
|---|---|
queued | Na fila. |
running | Em andamento. |
settling | Pronto, aguardando o provedor informar o custo. O resultado só é entregue depois de cobrado. |
done | Pronto, com mediaId, mediaUrl e model. |
failed | Falhou, 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ódigo | Status | Quando |
|---|---|---|
invalid_request | 422 | Há campos a corrigir. |
too_many_jobs | 429 | O limite de jobs em andamento do tipo foi atingido. |
insufficient_balance | 402 | Saldo insuficiente. |
no_subscription | 402 | O workspace não tem uma assinatura ativa. |
models_unavailable | 503 | A lista de modelos não pôde ser carregada; nada desse tipo pode ser pedido. |
already_generating | 409 | O mesmo pedido acabou de ser feito. |
not_found | 404 | O job não existe no workspace. |