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

> ## Agent Instructions
> The Venice API is OpenAI-compatible: use any OpenAI SDK with the base URL `https://api.venice.ai/api/v1` and a Venice API key, or pay per request from a USDC wallet through x402 with no account.
> Read model IDs from `GET /models` or `GET /models/traits` at runtime instead of hardcoding them from memory or from these pages. Models are added and retired often.
> Every model's price is in https://docs.venice.ai/pricing.md. Quote video and audio jobs with `POST /video/quote` or `POST /audio/quote` before you queue them.
> Search these docs from an MCP client at https://docs.venice.ai/mcp. The full agent guide is https://docs.venice.ai/agents.md.

# File inputs

> Allega PDF, documenti Office, file di testo, dati e codice sorgente alle richieste di chat completion di Venice per riassunti, Q&A e trasformazioni.

I file inputs ti permettono di allegare documenti e file sorgente direttamente a una richiesta `/chat/completions`. Venice estrae il file in testo prima di inviarlo al modello selezionato, quindi puoi porre domande, riassumere, confrontare o trasformare il contenuto del file senza prima costruire il tuo parser.

Usa i file inputs quando il tuo prompt dipende dal contenuto di un documento, foglio di calcolo, file markdown, file JSON o file di codice. Sono input legati alla richiesta, non storage persistente di file, quindi includi il file in ogni richiesta che ne ha bisogno.

> [!NOTE]
>
> I file inputs usano l'array di contenuto chat compatibile con OpenAI. Aggiungi un blocco di contenuto con `type: "file"` e fornisci il contenuto del file in `file.file_data`.

## Tipi di file supportati

L'API chat accetta i file inputs sia come data URL base64 sia come URL pubblicamente accessibili.

La dimensione massima del file è di **25MB per file**, misurata dopo la decodifica di un data URL base64 o dopo il fetch di un URL.

| Categoria | Formati |
| - | - |
| Documenti | PDF, DOCX, PPTX |
| Fogli di calcolo | XLSX, XLS, CSV |
| Testo e dati | TXT, Markdown, JSON |
| Codice sorgente | La maggior parte dei file di codice comuni, inclusi `.py`, `.js`, `.ts`, `.c`, `.cpp`, `.java`, `.go`, `.rs`, `.ps1`, `.sh`, `.yaml` e `.sql` |

> [!NOTE]
>
> I file vengono estratti in testo prima dell'inferenza. Il testo estratto conta verso il contesto di input del modello, quindi scegli un modello con `availableContextTokens` sufficienti per il file più le tue istruzioni e la risposta attesa.

## Utilizzo di base

Invia un array `messages` in cui il `content` del messaggio user è un array di blocchi di testo e di file:

```python Python theme={"system"}
import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VENICE_API_KEY"],
    base_url="https://api.venice.ai/api/v1",
)

path = Path("q3-report.pdf")
file_data = "data:application/pdf;base64," + base64.b64encode(path.read_bytes()).decode("utf-8")

response = client.chat.completions.create(
    model="openai-gpt-55",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Summarize this report in five bullets and list the main risks.",
                },
                {
                    "type": "file",
                    "file": {
                        "file_data": file_data,
                        "filename": "q3-report.pdf",
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)
```

```javascript Node.js theme={"system"}
import OpenAI from "openai";
import { readFile } from "node:fs/promises";

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: "https://api.venice.ai/api/v1",
});

const pdf = await readFile("q3-report.pdf");
const fileData = `data:application/pdf;base64,${pdf.toString("base64")}`;

const response = await client.chat.completions.create({
  model: "openai-gpt-55",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Summarize this report in five bullets and list the main risks.",
        },
        {
          type: "file",
          file: {
            file_data: fileData,
            filename: "q3-report.pdf",
          },
        },
      ],
    },
  ],
});

console.log(response.choices[0].message.content);
```

```bash cURL theme={"system"}
PDF_BASE64=$(base64 < q3-report.pdf | tr -d '\n')

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "openai-gpt-55",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this report in five bullets and list the main risks."
        },
        {
          "type": "file",
          "file": {
            "file_data": "data:application/pdf;base64,$PDF_BASE64",
            "filename": "q3-report.pdf"
          }
        }
      ]
    }
  ]
}
EOF
```

## URL di file

Se il file è già ospitato a un URL HTTP o HTTPS pubblico, passa l'URL in `file_data` invece di codificarlo in base64:

```json theme={"system"}
{
  "model": "openai-gpt-55",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Identify the governing law, renewal terms, and termination rights in this agreement."
        },
        {
          "type": "file",
          "file": {
            "file_data": "https://example.com/contracts/vendor-agreement.pdf",
            "filename": "vendor-agreement.pdf"
          }
        }
      ]
    }
  ]
}
```

> [!WARNING]
>
> Usa solo URL pubblici che Venice possa recuperare senza autenticazione. Per file privati, invia un data URL base64.

## File multipli

Puoi includere più di un blocco di file nello stesso messaggio. Metti una breve istruzione testuale prima dei file in modo che il modello sappia come utilizzarli.

```json theme={"system"}
{
  "model": "openai-gpt-55",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Compare these two policy drafts. Return the material differences and recommend which version is clearer."
        },
        {
          "type": "file",
          "file": {
            "file_data": "data:application/pdf;base64,JVBERi0xLjQK...",
            "filename": "policy-v1.pdf"
          }
        },
        {
          "type": "file",
          "file": {
            "file_data": "data:application/pdf;base64,JVBERi0xLjQK...",
            "filename": "policy-v2.pdf"
          }
        }
      ]
    }
  ]
}
```

Per risultati ottimali, dai un nome chiaro a ciascun file e fai riferimento a quei nomi nel tuo prompt.

## Data URL

Per i file locali, codifica i byte del file in base64 e anteponi il MIME type corretto:

| Tipo di file | Prefisso del data URL |
| - | - |
| PDF | `data:application/pdf;base64,` |
| DOCX | `data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,` |
| PPTX | `data:application/vnd.openxmlformats-officedocument.presentationml.presentation;base64,` |
| XLSX | `data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,` |
| CSV | `data:text/csv;base64,` |
| Markdown | `data:text/markdown;base64,` |
| Plain text | `data:text/plain;base64,` |
| JSON | `data:application/json;base64,` |

Se non conosci il MIME type esatto, usa `application/octet-stream`. Includere un `filename` accurato aiuta comunque Venice a identificare e visualizzare il file.

## Lavorare con file di grandi dimensioni

Poiché i file diventano testo del prompt, i file grandi possono aumentare latenza, utilizzo di token e costi. Tieni a mente la finestra di contesto del modello.

Il file raw deve essere di 25MB o meno. La codifica base64 aumenta la dimensione della richiesta di circa il 33%, quindi un file vicino al limite di 25MB produrrà un corpo JSON di richiesta più grande.

Buoni pattern per file di grandi dimensioni:

* Chiedi un compito specifico invece di un prompt generico "analizza tutto".
* Includi solo i documenti necessari per la risposta corrente.
* Usa modelli con `availableContextTokens` più ampi per report o codebase lunghi.
* Metti i documenti stabili e ripetuti prima delle domande dinamiche dell'utente se stai usando anche il [prompt caching](https://docs.venice.ai/guides/features/prompt-caching.md).
* Usa `stream: true` quando ti aspetti una risposta lunga.

### Limiti delle richieste

* **Per file:** ogni file deve essere di 25MB o meno.
* **Immagini:** un singolo messaggio può includere fino a 10 immagini. Il limite si applica per messaggio, non per richiesta.

### Quando un file fallisce

Un file che non può essere elaborato, ad esempio perché supera il limite di dimensione per file, non fa fallire l'intera richiesta. Venice sostituisce quel file con una nota di errore, il modello risponde comunque e la richiesta viene addebitata normalmente. Se una risposta sembra ignorare un file, verifica che il file rientri nei limiti indicati sopra prima di riprovare.

## File inputs vs. Text Parser

Usa i file inputs della chat quando vuoi che il modello ragioni immediatamente sul file.

Usa l'[API Text Parser](https://docs.venice.ai/api-reference/endpoint/augment/text-parser.md) quando vuoi prima estrarre il testo, ispezionare il conteggio dei token, memorizzare il testo estratto nel tuo sistema o inviare lo stesso testo estratto a più richieste.

| Necessità | Usa |
| - | - |
| Chiedere a un modello informazioni su un documento in una sola richiesta | File input chat |
| Estrarre testo senza inferenza del modello | API Text Parser |
| Controllare il conteggio dei token estratti prima del prompt | API Text Parser |
| Riutilizzare il testo estratto in molte richieste | API Text Parser, quindi includi il testo nei prompt |

## Best practice

* Includi `filename` quando possibile, specialmente quando invii più file.
* Metti l'istruzione prima dei blocchi di file in modo che il modello conosca il compito prima di leggere il contenuto estratto.
* Usa URL pubblici solo per file che possono essere recuperati senza cookie, header o stato di sessione firmato.
* Preferisci data URL base64 per file privati o file generati all'interno della tua applicazione.
* Fai domande mirate e specifica il formato di output che desideri.
* Per estrazioni strutturate, combina i file inputs con le [risposte strutturate](https://docs.venice.ai/guides/features/structured-responses.md).

## Risoluzione problemi

> [accordion] Il modello dice di non poter accedere al file
>
> Assicurati che il content del messaggio usi un array e includa un blocco `type: "file"`. Se hai usato un URL, verifica che sia raggiungibile pubblicamente senza autenticazione.

> [accordion] La richiesta è lenta o costosa
>
> Il file potrebbe estrarsi in una grande quantità di testo. Usa un modello con contesto più ampio, restringi il compito, invia meno file o pre-estrai e taglia il testo con l'API Text Parser.

> [accordion] La risposta ignora uno dei miei file
>
> Assegna a ciascun file un `filename` descrittivo e fai riferimento ai filename direttamente nel tuo prompt. Ad esempio, "Compare `policy-v1.pdf` against `policy-v2.pdf`."
>
> Se l'elaborazione del file è fallita, ad esempio perché superava i 25MB, il modello riceve al suo posto una nota di errore e risponde senza di esso. Vedi [Quando un file fallisce](#quando-un-file-fallisce).

> [accordion] Un modello rifiuta il contenuto del file
>
> I file inputs sono disponibili su modelli chat compatibili. Controlla la [pagina Modelli](https://docs.venice.ai/models/overview.md) per le capacità correnti del modello e i limiti di contesto, o prova un modello di testo recente con contesto ampio.


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