AiVideoEditor
Comece grátis
Menu

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

  1. Chame POST /api/v1/media/upload-intents com nome de arquivo, MIME declarado e contagem de bytes. Salve o assetId e o sessionId retornados como identidades separadas.
  2. Inspecione method. Para presigned_put, envie o arquivo inteiro para uploadUrl usando os cabeçalhos retornados. Para multipart_initiated, divida usando partSizeBytes, 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.
  3. Finalize em POST /api/v1/media/{assetId}/finalize com sessionId e, para multipart, multipart.parts contendo cada partNumber e etag.
  4. Use o ID do ativo finalizado no mediaIds do 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.