> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Caricare file sul CDN della piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

Carica file locali sul CDN della piattaforma AceDataCloud, ottieni un URL pubblicamente accessibile (nel formato `https://cdn.acedata.cloud/xxxxxx.png`), che può essere immediatamente referenziato nei parametri `image_url`, `reference_url` e simili di altre API aziendali (come Midjourney, Suno, Flux).

Scenari applicabili:

* Carica prima l'immagine di riferimento sul CDN per ottenere l'URL prima di chiamare Midjourney `/midjourney/imagine`.
* Memorizza nella cache il video generato nel passaggio precedente per usarlo come input del passaggio successivo.
* Ospita temporaneamente i materiali caricati dagli utenti, evitando di costruire un S3 autonomo.

> ℹ️ Questa API appartiene alle **API di gestione della piattaforma AceDataCloud**, con prefisso unificato `https://platform.acedata.cloud/api/v1/`.

## Panoramica dell'API

| Voce | Contenuto |
| - | - |
| Metodo | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/files/` |
| Autenticazione | ✅ Richiede un token dell'account |
| Content-Type | `multipart/form-data`（**non JSON**） |

## Descrizione dell'autenticazione (come ottenere il token dell'account)

Intestazione della richiesta:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

Metodo di ottenimento: accedi alla [piattaforma AceDataCloud](https://platform.acedata.cloud) → [console Account Token](https://platform.acedata.cloud/console/platform-tokens) → fai clic sul pulsante «Crea». Per i dettagli consulta [Gestire i token dell'account della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token).

## Corpo della richiesta (multipart/form-data)

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `file` | file | ✅ | Flusso di file binario. **Il limite predefinito per singolo file è 100 MB** |

## Esempi di richiesta

### cURL

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/files/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -F 'file=@./photo.jpg'
```

### Python

```python theme={null}
import os
import requests

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://platform.acedata.cloud/api/v1/files/",
        headers={
            "accept": "application/json",
            "authorization": f"Bearer {PLATFORM_TOKEN}",
        },
        files={"file": ("photo.jpg", f, "image/jpeg")},
        timeout=60,
    )

data = resp.json()
print(f"✅ 上传成功：{data['file_url']}")
# 直接用于其他业务接口：
# requests.post("https://api.acedata.cloud/midjourney/imagine",
#     json={"prompt": "...", "image_urls": [data["file_url"]]}, ...)
```

### Node.js

```javascript theme={null}
const fs = require('fs')
const FormData = require('form-data')

const form = new FormData()
form.append('file', fs.createReadStream('./photo.jpg'))

const r = await fetch('https://platform.acedata.cloud/api/v1/files/', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.PLATFORM_TOKEN}`,
    ...form.getHeaders(),
  },
  body: form,
})
const data = await r.json()
console.log('CDN URL:', data.file_url)
```

## Esempio di risposta (HTTP 200)

```json theme={null}
{
  "file_url": "https://cdn.acedata.cloud/qrd7gw.jpg"
}
```

Basta usare direttamente il campo `file_url` in altre API aziendali — l'URL CDN è attualmente pubblicamente accessibile e non richiede autenticazione; non considerarlo come una garanzia di archiviazione permanente.

## Descrizione dei campi di risposta

| Campo | Tipo | Descrizione |
| - | - | - |
| `file_url` | string | URL di accesso CDN |

## Gestione degli errori

| HTTP | Esempio di risposta | Significato |
| - | - | - |
| 400 | `{"error":"No file provided"}` | Il campo `file` non è stato allegato o il nome del campo è errato |
| 401 | Risposta di errore di autenticazione DRF | Token dell'account mancante o non valido |
| 413 | `{"error":"File too large","max_bytes":...}` | Il file supera i 100 MB (predefinito) |

## Suggerimenti pratici

* **Caricare immagini come immagini di riferimento**: `image_urls` di Midjourney, `image_url` di Flux e `reference_url` di Veo accettano tutti URL CDN, **non** accettano base64. Ottenere prima l'URL tramite questa API è un'operazione comune.
* **Non caricare dati sensibili**: l'URL restituito è pubblicamente accessibile; il periodo di conservazione è soggetto all'attuale politica di archiviazione della piattaforma, per l'archiviazione a lungo termine usa il tuo storage di oggetti.
* **Caricamenti in grandi quantità**: controlla la concorrenza e imposta un timeout per ogni caricamento; il throughput dipende dalla dimensione dei file e dall'ambiente di rete.

## API correlate

* [Ottenere l'elenco dei servizi della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — trova i servizi aziendali che accettano input URL
* [Creare credenziali API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — dopo il caricamento, di solito il passaggio successivo è creare credenziali per chiamare le API aziendali


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.