Funcionamiento de las cargas locales y remotas

Esta guía detalla el flujo completo para cargar archivos mediante la API V4 de Frame.io. Cubre las solicitudes y respuestas de API sin procesar tanto para cargas locales como remotas.

¿Busca guías específicas para SDK? Para implementaciones de carga con fragmentación, reintentos y seguimiento de progreso integrados, consulte la Guía de carga del SDK para Python.

Requisitos previos

Antes de empezar a cargar archivos, asegúrese de haber completado estos pasos de configuración:

1

Cuenta de Frame.io V4

Tiene una cuenta de Frame.io V4 administrada mediante Adobe Admin Console o ha cambiado a la autenticación de Adobe para el usuario de la cuenta

2

Configuración de Adobe Developer Console

Ha iniciado sesión en Adobe Developer Console y ha añadido la API de Frame.io a un proyecto nuevo o existente

3

Credenciales de autenticación

Ha generado las credenciales de autenticación adecuadas para el proyecto

4

Token de acceso

Ha usado correctamente esas credenciales para generar un token de acceso

Elección del método de carga

Hay dos formas de cargar un archivo mediante la API de Frame.io: Create File (local upload) y Create File (remote upload).

Carga local

Úsela cuando la aplicación pueda acceder al contenido multimedia de forma local, de forma similar a arrastrar un archivo desde el escritorio

Carga remota

Úsela cuando se acceda al contenido multimedia a través de la red, por ejemplo, mediante una integración con otro servicio

En esta guía empezaremos con el caso más sencillo: completar una carga remota.

Carga remota

Para crear un archivo mediante carga remota, seleccione el punto final Create File (remote upload). El cuerpo de la solicitud requiere el nombre del archivo y su URL de origen.

Actualmente, la carga remota tiene un límite de tamaño de archivo de 50 GB. Para archivos de más de 50 GB, utilice la carga local.

Ejemplo de solicitud

1{
2 "data": {
3 "name": "my_file.jpg",
4 "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
5 }
6}

Ejemplo de respuesta

Una solicitud correcta generará una respuesta como la siguiente:

1{
2 "data": {
3 "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 518,
8 "updated_at": "2025-06-26T20:14:33.796116Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:14:33.159489Z",
13 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e"
14 },
15 "links": {
16 "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status"
17 }
18}

Carga local

Para crear un archivo mediante carga local, seleccione el punto final Create File (local upload). El cuerpo de la solicitud requiere el nombre del archivo y el tamaño del archivo especificado en bytes.

Ejemplo de solicitud

1{
2 "data": {
3 "name": "my_file.jpg",
4 "file_size": 50645990
5 }
6}

Ejemplo de respuesta

Si la solicitud se completa correctamente, se crea un recurso de archivo marcador de posición sin contenido. En función del tamaño del archivo, el cuerpo de la respuesta incluirá una o varias upload_urls. En este ejemplo, tendremos que gestionar la carga en varias partes.

1{
2 "data": {
3 "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 50645990,
8 "updated_at": "2025-06-26T20:08:06.823170Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:08:06.751313Z",
13 "upload_urls": [
14 {
15 "size": 16881997,
16 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
17 },
18 {
19 "size": 16881997,
20 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
21 },
22 {
23 "size": 16881996,
24 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
25 }
26 ],
27 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
28 }
29}

Requisitos importantes de carga:

Estos son detalles importantes que debe tener en cuenta al enviar las solicitudes de carga posteriores:

  • El método de petición HTTP debe ser PUT
  • Debe incluirse el encabezado x-amz-acl y definirse como privado
  • El encabezado Content-Type debe coincidir con el valor media_type especificado en la solicitud Create File (local upload) original. Esto también se aplica al cargar el archivo en partes independientes. En el ejemplo anterior, el valor de media_type es image/jpeg. Por lo tanto, el valor de Content-Type también debe ser image/jpeg.

Carga de varias partes

Cuando un archivo determinado genera más de una URL de carga, deberá dividir el archivo de origen en fragmentos y emitir una solicitud PUT para cada uno.

Recomendado: La Guía de carga del SDK para Python cubre la carga de varias partes con FrameioUploader, que gestiona de forma integrada la fragmentación, las cargas paralelas, los reintentos y el seguimiento de progreso.

Si necesita implementar la carga manualmente, por ejemplo, en un lenguaje sin SDK o para tener control total sobre el proceso, el siguiente script muestra cómo dividir un archivo en fragmentos y cargar cada uno con las URL con firma previa.

Ejemplo de implementación de Python

Script de carga de varias partes
1import requests
2import math
3from typing import List
4from tqdm import tqdm # For progress bar
5
6def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
7 """
8 Upload a file in chunks using presigned URLs.
9 """
10 try:
11 # Auto-detect content type based on file extension
12 if content_type is None:
13 detected_content_type, _ = mimetypes.guess_type(file_path)
14 content_type = detected_content_type # Default fallback
15
16 print(f"Detected content type: {content_type}")
17
18 # Get file size
19 with open(file_path, 'rb') as f:
20 f.seek(0, 2) # Seek to end of file
21 file_size = f.tell()
22
23 # Calculate chunk size if not provided
24 if chunk_size is None:
25 chunk_size = math.ceil(file_size / len(upload_urls))
26
27 print(f"File size: {file_size} bytes")
28 print(f"Chunk size: {chunk_size} bytes")
29 print(f"Number of chunks: {len(upload_urls)}")
30
31 # Upload each chunk
32 with open(file_path, 'rb') as f:
33 with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
34 for i, url in enumerate(upload_urls):
35 start_byte = i * chunk_size
36 end_byte = min(start_byte + chunk_size, file_size)
37
38 # Read chunk from file
39 f.seek(start_byte)
40 chunk = f.read(end_byte - start_byte)
41
42 print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
43
44 # Upload chunk with minimal headers matching the signature
45 response = requests.put(
46 url,
47 data=chunk,
48 headers={
49 'content-type': content_type,
50 'x-amz-acl': 'private'
51 }
52 )
53
54 if response.status_code != 200:
55 print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
56 print(f"Response text: {response.text}")
57 print(f"Response headers: {dict(response.headers)}")
58 return False
59 else:
60 print(f"Chunk {i+1} uploaded successfully!")
61
62 pbar.update(1)
63
64 return True
65
66 except Exception as e:
67 print(f"Error during upload: {str(e)}")
68 return False
69
70# Example usage
71if __name__ == "__main__":
72 # Replace these with your actual values
73 file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
74 upload_urls = [
75 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
76 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
77 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
78 ]
79 content_type = "image/jpeg"
80
81 print("Starting file upload...")
82 success = upload_file_in_chunks(file_path, upload_urls, content_type)
83
84 if success:
85 print("File upload completed successfully!")
86 else:
87 print("File upload failed!")

Resumen del flujo de carga

1

Elección del método de carga

Decida entre carga remota, si se puede acceder al archivo mediante una URL, o carga local, si el archivo está en el sistema

2

Creación de solicitud de archivo

Realice la solicitud inicial para crear el recurso de archivo con los metadatos obligatorios

3

Gestión de URL de carga

En las cargas locales, procese las upload_urls devueltas, ya sea una sola parte o varias

4

Carga del contenido del archivo

Use solicitudes PUT con los encabezados adecuados para cargar el contenido del archivo en las URL proporcionadas

5

Verificación de la carga

Compruebe el estado del archivo para confirmar que la carga y el procesamiento se han completado correctamente

Siguientes pasos: Una vez cargado el archivo, puede usar el ID de archivo devuelto para añadir comentarios, crear elementos de uso compartido o realizar otras operaciones mediante la API V4 de Frame.io.