Como funcionam os métodos locais e remotos para fazer upload

Este guia detalha o fluxo completo para fazer upload de arquivos usando a API Frame.io V4. Ele aborda as solicitações e respostas brutas da API para os métodos local e remoto para fazer upload.

**Procurando guias específicos do SDK?**Para implementações para fazer upload com divisão em blocos integrada, novas tentativas e rastreamento de progresso, consulte o Guia para fazer upload do SDK para Python.

Pré-requisitos

Antes de começar a fazer upload de arquivos, verifique se você concluiu estas etapas de configuração:

1

Conta Frame.io V4

Você tem uma conta Frame.io V4 administrada por meio do Adobe Admin Console OU você mudou para a autenticação Adobe para o usuário da conta

2

Configuração do Adobe Developer Console

Você fez login no Adobe Developer Console e adicionou a API Frame.io a um projeto novo ou existente

3

Credenciais de autenticação

Você gerou as credenciais de autenticação apropriadas para o Projeto

4

Token de acesso

Você usou com sucesso essas credenciais para gerar um token de acesso

Escolher o método de upload

Há duas formas de fazer upload de um arquivo usando a API do Frame.io: Criar arquivo (upload local) e Criar arquivo (upload remoto).

Upload local

Use quando a mídia estiver acessível localmente ao aplicativo, semelhante a arrastar um arquivo do desktop

Fazer upload remoto

Use quando a mídia for acessada pela rede, como por meio de uma integração com outro serviço

Neste guia, começaremos com o caso mais simples: concluir um upload remoto.

Fazer upload remoto

Para criar um arquivo por meio de upload remoto, selecione o ponto de acesso Criar arquivo (upload remoto). O corpo da solicitação exige o nome do arquivo e a URL de origem.

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

Exemplo de solicitação

{
"data": {
"name": "my_file.jpg",
"source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
}
}

Exemplo de resposta

Uma solicitação bem-sucedida retornará uma resposta como a abaixo:

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

Upload local

Para criar um arquivo por meio de upload local, selecione o ponto de acesso Criar arquivo (fazer upload local). O corpo da solicitação exige o nome do arquivo e o tamanho do arquivo especificado em bytes.

Exemplo de solicitação

{
"data": {
"name": "my_file.jpg",
"file_size": 50645990
}
}

Exemplo de resposta

Se a solicitação for bem-sucedida, um recurso de arquivo placeholder será criado sem nenhum conteúdo. Dependendo do tamanho do arquivo, o corpo da resposta incluirá um ou mais upload_urls. Considerando este exemplo, precisaremos gerenciar esse processo para fazer upload em várias partes.

{
"data": {
"id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
"name": "my_file.jpg",
"status": "created",
"type": "file",
"file_size": 50645990,
"updated_at": "2025-06-26T20:08:06.823170Z",
"media_type": "image/jpeg",
"parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
"project_id": "7e46e495-4444-4555-8649-bee4d391a997",
"created_at": "2025-06-26T20:08:06.751313Z",
"upload_urls": [
{
"size": 16881997,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
},
{
"size": 16881997,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
},
{
"size": 16881996,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
}
],
"view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
}
}

Requisitos importantes de upload:

Estes são detalhes importantes a ter em mente ao enviar as solicitações subsequentes para fazer upload:

  • O método de solicitação HTTP deve ser PUT
  • O cabeçalho x-amz-acl deve ser incluído e definido como private
  • O cabeçalho Content-Type deve corresponder ao media_type especificado na solicitação original Criar arquivo (fazer upload local). Isso é verdadeiro mesmo ao fazer upload do arquivo em partes separadas. No exemplo acima, o valor para media_type é image/jpeg. Portanto, o valor para Content-Type também deve ser image/jpeg.

Upload em várias partes

Quando um arquivo resultar em mais de uma URL para fazer upload, você precisará dividir o arquivo de origem em blocos e emitir uma solicitação PUT para cada um.

Recomendação: o Guia para fazer upload do SDK para Python aborda o upload em várias partes usando FrameioUploader, que processa divisão em blocos, uploads paralelos, novas tentativas e rastreamento de progresso imediatamente.

Se precisar implementar manualmente o processo para fazer upload, por exemplo, em uma linguagem sem SDK ou para ter controle total sobre o processo, o script abaixo mostra como dividir um arquivo em blocos e fazer upload de cada um usando as URLs pré-assinadas.

Exemplo de implementação em Python

Script de upload em várias partes
import requests
import math
from typing import List
from tqdm import tqdm # For progress bar
def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
"""
Upload a file in chunks using presigned URLs.
"""
try:
# Auto-detect content type based on file extension
if content_type is None:
detected_content_type, _ = mimetypes.guess_type(file_path)
content_type = detected_content_type # Default fallback
print(f"Detected content type: {content_type}")
# Get file size
with open(file_path, 'rb') as f:
f.seek(0, 2) # Seek to end of file
file_size = f.tell()
# Calculate chunk size if not provided
if chunk_size is None:
chunk_size = math.ceil(file_size / len(upload_urls))
print(f"File size: {file_size} bytes")
print(f"Chunk size: {chunk_size} bytes")
print(f"Number of chunks: {len(upload_urls)}")
# Upload each chunk
with open(file_path, 'rb') as f:
with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
for i, url in enumerate(upload_urls):
start_byte = i * chunk_size
end_byte = min(start_byte + chunk_size, file_size)
# Read chunk from file
f.seek(start_byte)
chunk = f.read(end_byte - start_byte)
print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
# Upload chunk with minimal headers matching the signature
response = requests.put(
url,
data=chunk,
headers={
'content-type': content_type,
'x-amz-acl': 'private'
}
)
if response.status_code != 200:
print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
print(f"Response text: {response.text}")
print(f"Response headers: {dict(response.headers)}")
return False
else:
print(f"Chunk {i+1} uploaded successfully!")
pbar.update(1)
return True
except Exception as e:
print(f"Error during upload: {str(e)}")
return False
# Example usage
if __name__ == "__main__":
# Replace these with your actual values
file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
upload_urls = [
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
]
content_type = "image/jpeg"
print("Starting file upload...")
success = upload_file_in_chunks(file_path, upload_urls, content_type)
if success:
print("File upload completed successfully!")
else:
print("File upload failed!")

Resumo do fluxo de upload

1

Escolher método de upload

Escolha entre upload remoto (arquivo acessível por URL) ou upload local (arquivo no seu sistema)

2

Criar solicitação de arquivo

Faça a solicitação inicial para criar o recurso de arquivo com os metadados obrigatórios

3

Processar URLs de upload

Para uploads locais, processe os upload_urls retornados (em uma ou várias partes)

4

Fazer upload do conteúdo do arquivo

Use solicitações PUT com os cabeçalhos adequados para fazer upload do conteúdo do arquivo para as URLs fornecidas

5

Verificar upload

Verifique o status do arquivo para confirmar que o upload e o processamento foram concluídos com sucesso

Próximas etapas: depois que o upload do arquivo for concluído, você poderá usar o ID de arquivo retornado para adicionar comentários, criar compartilhamentos ou executar outras operações usando a API Frame.io V4.