> This page is for Piattaforma, version V4 sperimentale.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# Come funzionano i caricamenti locali e remoti

Questa guida illustra nel dettaglio l'intero flusso per caricare file utilizzando l'API Frame.io V4. Copre richieste e risposte API non elaborate per i caricamenti locali e remoti.

> **Info**
>
> **Cerchi guide specifiche per gli SDK?** Per implementare caricamenti con funzioni integrate di suddivisione in chunk, nuovi tentativi e tracciamento dello stato di avanzamento, consulta la [guida al caricamento dell'SDK Python](./python-sdk-upload-guide).

## Prerequisiti

Prima di iniziare a caricare i file, assicurati di aver completato questi passaggi di configurazione:

#### Account Frame.io V4

Hai un account Frame.io V4 amministrato tramite [Adobe Admin Console](https://adminconsole.adobe.com/), OPPURE sei [passato all'autenticazione Adobe](https://help.frame.io/it/articles/11758018-connecting-to-adobe-authentication) per l'utente dell'account

#### Configurazione di Adobe Developer Console

Hai effettuato l'accesso ad [Adobe Developer Console](https://developer.adobe.com/console) e hai aggiunto l'API Frame.io a un progetto nuovo o esistente

#### Credenziali di autenticazione

Hai generato le [credenziali di autenticazione appropriate](https://developer.adobe.com/frameio/guides/Authentication/) per il tuo progetto

#### Token di accesso

Hai utilizzato con successo quelle credenziali per generare un token di accesso

## Scelta del metodo di caricamento

Esistono due modi per caricare un file utilizzando l'API Frame.io: `Create File (local upload)` e `Create File (remote upload)`.

#### Caricamento locale

Da utilizzare quando i media sono accessibili localmente alla tua applicazione; è simile al trascinamento di un file dal desktop

#### Caricamento remoto

Da utilizzare quando i media sono accessibili tramite rete, ad esempio attraverso un'integrazione con un altro servizio

In questa guida inizieremo con il caso più semplice del completamento di un caricamento remoto.

## Caricamento remoto

Per creare un file tramite caricamento remoto, seleziona l'endpoint**Create File (remote upload)**. Il corpo della richiesta richiede il nome del file e il suo URL di origine.

> **Warning**
>
> Il caricamento remoto ha attualmente un **limite di dimensione del file di 50 GB**. Per file più grandi di 50 GB, utilizza il [caricamento locale](#local-upload).

### Esempio di richiesta

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

### Esempio di risposta

Una richiesta riuscita restituirà una risposta come quella di seguito:

```json
{
    "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"
    }
}
```

## Caricamento locale

Per creare un file tramite caricamento locale, seleziona l'endpoint**Create File (local upload)**. Il corpo della richiesta richiede il nome del file e la sua dimensione specificata in byte.

### Esempio di richiesta

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

### Esempio di risposta

Se la richiesta riesce, viene creata una risorsa di file segnaposto senza contenuto. In base alla dimensione del file, il corpo della risposta includerà uno o più `upload_url`. In base a questo esempio, dovremo gestire il caricamento in più parti.

```json
{
    "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"
    }
}
```

> **Warning**
>
> **Requisiti di caricamento importanti:**
>
> Questi sono alcuni dettagli importanti da tenere presenti quando invii le successive richieste di caricamento:
>
> * Il metodo di richiesta HTTP deve essere `PUT`
> * L'intestazione `x-amz-acl` deve essere inclusa e impostata su private
> * L'intestazione `Content-Type` deve corrispondere al `media_type` specificato nella richiesta **Create File (local upload)** originale. Questo vale anche durante il caricamento del file come parti separate. Nell'esempio precedente, il valore per `media_type` è `image/jpeg`. Pertanto, anche il valore per `Content-Type` deve essere `image/jpeg`.

## Caricamento multi-parte

Quando un determinato file restituisce più di un URL di caricamento, occorre dividere il file di origine in chunk e inviare una richiesta PUT per ciascuno.

> **Info**
>
> **Consigliato:** la [guida al caricamento dell'SDK Python](./python-sdk-upload-guide) tratta il caricamento multi-parte usando `FrameioUploader`, che gestisce automaticamente la suddivisione in chunk, i caricamenti paralleli, i nuovi tentativi e il tracciamento dello stato di avanzamento.

Se devi implementare il caricamento manualmente, ad esempio in un linguaggio senza SDK o per il controllo completo del processo, lo script in basso mostra come dividere un file in chunk e come caricare ciascuno usando gli URL pre-firmati.

### Esempio di implementazione Python

**`Script di caricamento multi-parte`**

```python title="Script di caricamento multi-parte"
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!")
```

## Riepilogo del flusso caricamento

#### Scegli il metodo di caricamento

Decidi tra caricamento remoto (file accessibile tramite URL) o caricamento locale (file sul sistema)

#### Crea una richiesta di file

Effettua la richiesta iniziale per creare la risorsa di file con i metadati necessari

#### Gestisci l'URL di caricamento

Per i caricamenti locali, elabora gli upload\_url restituiti (singola parte o multi-parte)

#### Carica il contenuto del file

Usa richieste PUT con le intestazioni appropriate per caricare il contenuto del file sugli URL forniti

#### Verifica il caricamento

Controlla lo stato del file per confermare che il caricamento e l'elaborazione siano riusciti

> **Info**
>
> **Passaggi successivi**: una volta caricato il file, puoi usare l'ID file restituito per aggiungere commenti, creare condivisioni o eseguire altre operazioni usando l'API Frame.io V4.