GuiasFazendo upload para o Frame.io

Frame.io Python SDK - Guia para fazer upload

Este guia explica como fazer upload de arquivos para o Frame.io usando o Frame.io Python SDKK (frameio). O SDK processa uploads fragmentados em blocos para o S3 por meio de URLs pré-assinadas, com workers paralelos, novas tentativas automáticas e rastreamento de progresso opcional. Para obter conceitos gerais da API de upload, como URLs para fazer upload, cabeçalhos e divisão em blocos, consulte Como funcionam os uploads locais e remotos.

Pré-requisitos

1

Autenticação

Você tem um cliente Frameio funcionando. Consulte o Guia de autenticação para configuração.

2

Instalar o SDK

    pip install frameio
3

Pasta de destino

Você precisa do account_id e folder_id onde o arquivo deve receber upload. Use o SDK para encontrá-los:

    # List your accounts
    accounts = client.accounts.index()
    account_id = accounts.data[0].id
    # List workspaces in the account
    workspaces = client.workspaces.index(account_id=account_id)
    workspace_id = workspaces.data[0].id
    # List projects in the workspace
    projects = client.projects.index(account_id=account_id, workspace_id=workspace_id)
    project = projects.data[0]
    # The project's root folder is the top-level upload target
    folder_id = project.root_folder_id
    # Or list subfolders to upload into a specific one
    folders = client.folders.list(account_id=account_id, folder_id=folder_id)

Início rápido

import os
from frameio import Frameio
from frameio.files import FileCreateLocalUploadParamsData
from frameio.upload import FrameioUploader
client = Frameio(token="YOUR_TOKEN")
file_path = "/path/to/video.mp4"
file_size = os.path.getsize(file_path)
# 1. Create the file resource and get pre-signed upload URLs
response = client.files.create_local_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateLocalUploadParamsData(
        name="video.mp4",
        file_size=file_size,
    ),
)
# 2. Upload the file to S3
with open(file_path, "rb") as f:
    FrameioUploader(response.data, f).upload()

É isso. O SDK divide o arquivo em blocos com base nas URLs para fazer upload retornadas pela API, faz upload deles em paralelo e processa novas tentativas automaticamente.

Como funciona

Fazer upload local é um processo em duas etapas:

1

Criar recurso de arquivo

Chame client.files.create_local_upload() com o nome e o tamanho do arquivo. A API cria um arquivo placeholder e retorna URLs S3 PUT pré-assinadas, uma por bloco. O número de URLs e, portanto, de blocos depende do tamanho do arquivo.

2

Fazer upload para o S3

FrameioUploader lê as URLs para fazer upload da resposta, divide o arquivo em blocos correspondentes e faz PUT de cada bloco na respectiva URL em paralelo usando um pool de threads. Cada solicitação inclui os cabeçalhos obrigatórios x-amz-acl: private e Content-Type.

O upload vai diretamente do seu aplicativo para o S3; ele não passa pelos servidores da API do Frame.io. Esse é o mesmo padrão usado por serviços como YouTube, Vimeo e Dropbox para fazer upload de arquivos grandes.

Uso do FrameioUploader

FrameioUploader é a forma recomendada de fazer upload de arquivos. Ele encapsula o uploader em blocos de nível inferior e processa todos os detalhes: extrair URLs para fazer upload da resposta da API, definir os cabeçalhos obrigatórios, dividir o arquivo em blocos e fazer upload em paralelo.

Rastreamento de progresso

Use o callback on_progress para rastrear o progresso do upload:

def on_progress(bytes_uploaded: int, total_bytes: int) -> None:
    pct = bytes_uploaded / total_bytes * 100
    print(f"\r{pct:.1f}% ({bytes_uploaded:,} / {total_bytes:,} bytes)", end="", flush=True)
with open(file_path, "rb") as f:
    FrameioUploader(response.data, f, on_progress=on_progress).upload()
print("\nUpload complete!")

O callback é invocado uma vez após a conclusão de cada bloco, com os bytes cumulativos cujo upload foi feito até o momento e o tamanho total do arquivo.

Barra de progresso Rich

Para uma experiência refinada no terminal, use Rich:

from rich.progress import Progress, BarColumn, DownloadColumn, TransferSpeedColumn, TimeRemainingColumn
with Progress(
    "[progress.description]{task.description}",
    BarColumn(),
    DownloadColumn(),
    TransferSpeedColumn(),
    TimeRemainingColumn(),
) as progress:
    task = progress.add_task("Uploading...", total=file_size)
    with open(file_path, "rb") as f:
        FrameioUploader(
            response.data, f,
            on_progress=lambda done, total: progress.update(task, completed=done),
        ).upload()

Configuração

FrameioUploader aceita vários parâmetros opcionais:

ParâmetroPadrãoDescrição
max_workers5Número de threads simultâneas para fazer upload
headers{"x-amz-acl": "private"}Cabeçalhos enviados com cada solicitação S3 PUT. Cabeçalhos personalizados são mesclados com os padrões.
max_retries3Tentativas de repetição por bloco (backoff exponencial: 1s, 2s, 4s, …)
on_progressNenhumCallback (bytes_uploaded, total_bytes) disparado após cada bloco
with open(file_path, "rb") as f:
    FrameioUploader(
        response.data,
        f,
        max_workers=10,       # more parallelism for high-bandwidth connections
        max_retries=5,        # more resilient on flaky networks
        on_progress=on_progress,
    ).upload()

Exemplo completo

Um exemplo completo com autenticação, upload e rastreamento de progresso:

import os
from frameio import Frameio
from frameio.auth import ServerToServerAuth
from frameio.files import FileCreateLocalUploadParamsData
from frameio.upload import FrameioUploader
# Authenticate
auth = ServerToServerAuth(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)
client = Frameio(token=auth.get_token)
# Prepare the file
file_path = "/path/to/video.mp4"
file_name = os.path.basename(file_path)
file_size = os.path.getsize(file_path)
# Create the file resource
response = client.files.create_local_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateLocalUploadParamsData(
        name=file_name,
        file_size=file_size,
    ),
)
print(f"Uploading {file_name} ({file_size:,} bytes) in {len(response.data.upload_urls)} chunks...")
# Upload with progress
def on_progress(uploaded: int, total: int) -> None:
    print(f"\r{uploaded / total:.0%}", end="", flush=True)
with open(file_path, "rb") as f:
    FrameioUploader(response.data, f, on_progress=on_progress).upload()
print(f"\nDone! View at: {response.data.view_url}")

Se precisar de controle total sobre o processo de fazer upload, por exemplo, para lidar manualmente com a divisão em blocos, integrar com um pipeline async ou personalizar a lógica de nova tentativa, consulte Como funcionam os uploads locais e remotos para ver o fluxo bruto da API e um exemplo de script Python independente.

Fazer upload remoto

Se o arquivo já estiver acessível por meio de uma URL pública, use o upload remoto. Não é necessário dividir em blocos. O Frame.io busca o arquivo diretamente:

from frameio.files import FileCreateRemoteUploadParamsData
response = client.files.create_remote_upload(
    account_id="YOUR_ACCOUNT_ID",
    folder_id="YOUR_FOLDER_ID",
    data=FileCreateRemoteUploadParamsData(
        name="video.mp4",
        source_url="https://example.com/video.mp4",
    ),
)
print(f"File created: {response.data.id}")

No momento, o upload remoto tem um limite de tamanho de arquivo de 50 GB. Para arquivos maiores que 50 GB, use upload local.

Verificação do status do upload

Após fazer upload, você pode verificar se o arquivo foi recebido:

status = client.files.show_file_upload_status(
    account_id="YOUR_ACCOUNT_ID",
    file_id=response.data.id,
)
print(f"Upload complete: {status.data.upload_complete}")