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
- Llama a
POST /api/v1/media/upload-intentscon el nombre de archivo, el MIME declarado y el número de bytes. Guarda elassetIdy elsessionIddevueltos como identidades separadas. - Inspecciona
method. Parapresigned_put, sube el archivo completo auploadUrlusando las cabeceras devueltas. Paramultipart_initiated, divídelo usandopartSizeBytes, 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. - Finaliza en
POST /api/v1/media/{assetId}/finalizeconsessionIdy, para multipart,multipart.partsque contenga cadapartNumberyetag. - Usa el ID del recurso finalizado en el
mediaIdsdel 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.