Vai al contenuto
Riferimento API
Riferimento API

Creare un File Upload

Carica un file locale, un URL HTTPS remoto o una sorgente base64 e ricevi un URL temporaneo.

Visualizza Markdown

Carica un file locale, un URL HTTPS remoto o una sorgente base64 e ricevi un URL temporaneo.

Endpoint

POST /api/v1/files
URL di base
https://runapi.ai
Versione API
v1
Autenticazione
Authorization: Bearer YOUR_API_KEY
02

Richiesta

Corpo JSON

Invia i valori solo nella posizione di richiesta elencata.

application/json - Base64 source4 campi
file_namestring
Opzionale

Nome file opzionale per il File Upload creato.

sourceobject
Obbligatorio

Byte sorgente codificati in Base64.

source.datastring
Obbligatorio

Dati Base64

source.typestring
Obbligatorio

Seleziona la rappresentazione sorgente base64.

application/json - URL source4 campi
file_namestring
Opzionale

Nome file opzionale per il File Upload creato.

sourceobject
Obbligatorio

Sorgente HTTPS remota da scaricare.

source.typestring
Obbligatorio

Seleziona la rappresentazione sorgente tramite URL.

source.urlstring
Obbligatorio

URL HTTPS pubblico da scaricare.

multipart/form-data2 campi
filestring
Obbligatorio

Byte del file locale da caricare.

file_namestring
Opzionale

Nome file opzionale per il File Upload creato.

03

Risposta di successo

HTTP 201

POST /api/v1/files

JSON 
{
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-27T11:00:00.000Z",
  "file_name": "mask.png",
  "mime_type": "image/png",
  "size_bytes": 204800,
  "url": "https://file.runapi.ai/temp/user-uploads/mask.png"
}
04

Risposta di errore (401)

HTTP 401
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Authentication required"
}
05

Risposta di errore (403)

HTTP 403
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Standard API key required"
}
06

Risposta di errore (400)

HTTP 400
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Only HTTPS URLs are allowed"
}
07

Risposta di errore (408)

HTTP 408
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Download timeout"
}
08

Risposta di errore (413)

HTTP 413
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "File size exceeds the maximum allowed size"
}
09

Risposta di errore (415)

HTTP 415
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "This content type is not supported"
}
10

Risposta di errore (422)

HTTP 422
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "File upload failed. Please try again."
}
11

Risposta di errore (429)

HTTP 429
Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Too many file uploads for this account. Please retry later."
}
12

Esempio cURL

CURL 
curl -X POST https://runapi.ai/api/v1/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}'