AiVideoEditor
Empieza gratis
Menú

Revisada el 2026-11-10 · Versión de API 2026-11-09 · Leer Markdown

Subir y conservar medios

Los bytes de los medios viajan directamente a un almacenamiento de objetos privado temporal. REST y MCP devuelven instrucciones de subida; no aceptan contenido binario de archivos en el JSON de las herramientas. El almacenamiento debe estar configurado en el despliegue o la creación de la subida devuelve provider_unavailable.

Ciclo de vida de la subida

  1. Llama a POST /api/v1/media/upload-intents con el nombre de archivo, el MIME declarado y el número de bytes. Guarda el assetId y el sessionId devueltos como identidades separadas.
  2. Inspecciona method. Para presigned_put, sube el archivo completo a uploadUrl usando las cabeceras devueltas. Para multipart_initiated, divídelo usando partSizeBytes, sube cada parte numerada a su URL devuelta y conserva su recibo ETag. Nunca añadas la clave bearer de AiVideoEditor a las solicitudes de almacenamiento.
  3. Finaliza en POST /api/v1/media/{assetId}/finalize con sessionId y, para multipart, multipart.parts que contenga cada partNumber y etag.
  4. Usa el ID del recurso finalizado en el mediaIds del borrador. Una intención de subida por sí sola no hace que el recurso sea publicable.

El servidor observa los bytes y el formato reales sobre una copia final inmutable. El tamaño/MIME declarados son entradas de reserva, no prueba de la validez del archivo. Las familias básicas compatibles son JPEG, PNG y MP4; los destinos individuales pueden imponer límites más estrictos. El tamaño máximo de archivo actual es 500 MiB (524,288,000 bytes). Los archivos de 50 MiB o más usan multipart, normalmente con partes de 16 MiB. Sigue siempre los tamaños, URLs y caducidades devueltas en lugar de deducirlos de estos valores por defecto.

{
  "sessionId": "<session UUID from upload-intents>",
  "multipart": {
    "parts": [
      { "partNumber": 1, "etag": "<ETag returned by storage>" }
    ]
  }
}

Esta es una ilustración de la forma multipart; incluye cada parte real. La finalización de PUT único envía solo sessionId. Da a cada mutación de API nueva su propia Idempotency-Key; consérvala para repeticiones idénticas seguras.

Reanudar o abandonar

Las URLs firmadas caducadas no son direcciones permanentes de medios. Solicita URLs de partes multipart nuevas con POST /media/{id}/upload-parts usando fromPart y toPart (un rango inclusivo de como máximo 64 partes). Consulta la referencia de la API para la forma acotada de la solicitud. No vuelvas a subir partes completadas innecesariamente ni completes el ensamblado multipart directamente a través del almacenamiento: la finalización está controlada por el servidor.

Usa POST /media/{id}/abandon al cancelar una subida incompleta. Esto libera su reserva a través del flujo de limpieza compartido. La caducidad de la sesión o el consumo del estado multipart pueden requerir una nueva intención; no adivines las claves de objetos del almacenamiento.

Retención temporal

GET /media/{id} devuelve el estado y la información dinámica de deleteAfter, no una URL pública permanente. Los usos programados y en vuelo protegen los medios durante el trabajo. La política por defecto conserva los medios de borrador sin usar durante 14 días, los medios resueltos durante 72 horas, y el trabajo fallido o ambiguo durante 7 días después del intento correspondiente. La retención real depende de todas las referencias restantes; deleteAfter puede ser null. Conserva los originales. Si los medios están caducados o eliminándose, súbelos de nuevo antes de publicar.