Revisado em 2026-11-10 · Versão da API 2026-11-09 · Ler Markdown
Envio e retenção de mídia
Os bytes de mídia vão diretamente para um armazenamento de objetos privado temporário. A REST e o MCP
retornam instruções de upload; eles não aceitam conteúdo binário de arquivo no JSON das ferramentas.
O armazenamento deve estar configurado na implantação, ou a criação do upload retorna
provider_unavailable.
Ciclo de vida do upload
- Chame
POST /api/v1/media/upload-intentscom nome de arquivo, MIME declarado e contagem de bytes. Salve oassetIde osessionIdretornados como identidades separadas. - Inspecione
method. Parapresigned_put, envie o arquivo inteiro parauploadUrlusando os cabeçalhos retornados. Paramultipart_initiated, divida usandopartSizeBytes, envie cada parte numerada para sua URL retornada e guarde o recibo de ETag dela. Nunca adicione a chave bearer do AiVideoEditor às requisições de armazenamento. - Finalize em
POST /api/v1/media/{assetId}/finalizecomsessionIde, para multipart,multipart.partscontendo cadapartNumbereetag. - Use o ID do ativo finalizado no
mediaIdsdo rascunho. Uma intent de upload sozinha não torna o ativo publicável.
O servidor observa os bytes e o formato reais em uma cópia final imutável. O tamanho/MIME declarados são entradas de reserva, não prova de validade do arquivo. As famílias básicas suportadas são JPEG, PNG e MP4; destinos individuais podem impor limites mais rigorosos. O tamanho máximo atual de arquivo é 500 MiB (524.288.000 bytes). Arquivos de 50 MiB ou mais usam multipart, normalmente com partes de 16 MiB. Siga sempre os tamanhos, URLs e expirações retornados, em vez de derivá-los desses padrões.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Esta é uma ilustração do formato multipart; inclua todas as partes reais. A finalização
por PUT único envia apenas o sessionId. Dê a cada nova mutação da API o seu próprio
Idempotency-Key; guarde-a para repetições idênticas seguras.
Retomar ou abandonar
URLs assinadas expiradas não são endereços permanentes de mídia. Solicite URLs novas de partes
multipart com POST /media/{id}/upload-parts usando fromPart e toPart (um intervalo inclusivo de no máximo 64 partes). Consulte a referência da API para o formato
limitado da solicitação. Não reenvie partes concluídas desnecessariamente nem conclua a
montagem multipart diretamente no armazenamento: a finalização é controlada pelo servidor.
Use POST /media/{id}/abandon ao cancelar um upload incompleto. Isso libera
a reserva dele por meio do fluxo de limpeza compartilhado. A expiração da sessão ou o estado
multipart já consumido podem exigir uma nova intent; não adivinhe as chaves de objetos do armazenamento.
Retenção temporária
GET /media/{id} retorna o status e as informações dinâmicas de deleteAfter, não uma
URL pública permanente. Usos agendados e em andamento protegem a mídia durante o trabalho.
A política padrão retém mídia de rascunho não utilizada por 14 dias, mídia já resolvida por 72 horas
e trabalho com falha ou ambíguo por 7 dias após a tentativa correspondente. A retenção
real depende de todas as referências restantes; deleteAfter pode ser nulo.
Guarde os originais. Se a mídia estiver expirada ou em exclusão, envie-a novamente antes de publicar.