> ## 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.
# File inputs
> Anexe PDFs, documentos Office, arquivos de texto, dados e código a requisições de chat completion da Venice para resumir, perguntar e transformar.
File inputs permitem que você anexe documentos e arquivos-fonte diretamente a uma requisição `/chat/completions`. A Venice extrai o arquivo para texto antes de enviá-lo ao modelo selecionado, para que você possa fazer perguntas, resumir, comparar ou transformar o conteúdo de arquivos sem precisar construir seu próprio parser primeiro.
Use file inputs quando seu prompt depender do conteúdo de um documento, planilha, arquivo markdown, arquivo JSON ou arquivo de código. São entradas vinculadas à requisição, não armazenamento persistente de arquivos, então inclua o arquivo em cada requisição que precisar dele.
File inputs usam o array de conteúdo de chat compatível com OpenAI. Adicione um bloco de conteúdo com `type: "file"` e forneça o conteúdo do arquivo em `file.file_data`.
## Tipos de arquivo suportados
A API de chat aceita file inputs como data URLs em base64 ou URLs publicamente acessíveis.
O tamanho máximo de arquivo é **25 MB por arquivo**, medido após decodificar uma data URL base64 ou após buscar uma URL.
| Categoria | Formatos |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Documentos | PDF, DOCX, PPTX |
| Planilhas | XLSX, XLS, CSV |
| Texto e dados | TXT, Markdown, JSON |
| Código-fonte | Arquivos de código mais comuns, incluindo `.py`, `.js`, `.ts`, `.c`, `.cpp`, `.java`, `.go`, `.rs`, `.ps1`, `.sh`, `.yaml` e `.sql` |
Os arquivos são extraídos para texto antes da inferência. O texto extraído conta para o contexto de entrada do modelo, então escolha um modelo com `availableContextTokens` suficiente para o arquivo mais suas instruções e a resposta esperada.
## Uso básico
Envie um array `messages` em que o `content` da mensagem do usuário seja um array de blocos de texto e de arquivo:
```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 @- <
## URLs de arquivo
Se o arquivo já estiver hospedado em uma URL HTTP ou HTTPS pública, passe a URL em `file_data` em vez de codificá-la em 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"
}
}
]
}
]
}
```
Use apenas URLs públicas que a Venice consiga buscar sem autenticação. Para arquivos privados, envie uma data URL em base64.
## Múltiplos arquivos
Você pode incluir mais de um bloco de arquivo na mesma mensagem. Coloque uma breve instrução de texto antes dos arquivos para que o modelo saiba como usá-los.
```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"
}
}
]
}
]
}
```
Para melhores resultados, nomeie cada arquivo claramente e refira-se a esses nomes no seu prompt.
## Data URLs
Para arquivos locais, codifique os bytes do arquivo como base64 e adicione o prefixo do tipo MIME correto:
| Tipo de arquivo | Prefixo da 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,` |
| Texto simples | `data:text/plain;base64,` |
| JSON | `data:application/json;base64,` |
Se você não souber o tipo MIME exato, use `application/octet-stream`. Incluir um `filename` preciso ainda ajuda a Venice a identificar e exibir o arquivo.
## Trabalhando com arquivos grandes
Como os arquivos viram texto do prompt, arquivos grandes podem aumentar latência, uso de tokens e custo. Tenha em mente a janela de contexto do modelo.
O arquivo bruto deve ter 25 MB ou menos. A codificação em base64 aumenta o tamanho da requisição em cerca de 33%, então um arquivo perto do limite de 25 MB produzirá um corpo de requisição JSON maior.
Bons padrões para arquivos grandes:
* Peça por uma tarefa específica em vez de um prompt amplo de "analise tudo".
* Inclua apenas os documentos necessários para a resposta atual.
* Use modelos com `availableContextTokens` maior para relatórios longos ou bases de código.
* Coloque documentos estáveis e repetidos antes de perguntas dinâmicas do usuário se você também estiver usando [prompt caching](/guides/features/prompt-caching).
* Use `stream: true` quando esperar uma resposta longa.
## File inputs vs. Text Parser
Use file inputs de chat quando quiser que o modelo raciocine sobre o arquivo imediatamente.
Use a [API Text Parser](/api-reference/endpoint/augment/text-parser) quando quiser extrair o texto primeiro, inspecionar a contagem de tokens, armazenar o texto extraído em seu próprio sistema ou enviar o mesmo texto extraído para múltiplas requisições.
| Necessidade | Use |
| ---------------------------------------------------------------- | -------------------------------------------------- |
| Perguntar ao modelo sobre um documento em uma única requisição | File input de chat |
| Extrair texto sem inferência do modelo | API Text Parser |
| Verificar a contagem de tokens extraídos antes de fazer o prompt | API Text Parser |
| Reutilizar texto extraído em muitas requisições | API Text Parser, depois inclua o texto nos prompts |
## Melhores práticas
* Inclua `filename` sempre que possível, especialmente ao enviar múltiplos arquivos.
* Coloque a instrução antes dos blocos de arquivo para que o modelo saiba a tarefa antes de ler o conteúdo extraído.
* Use URLs públicas apenas para arquivos que possam ser buscados sem cookies, cabeçalhos ou estado de sessão assinado.
* Prefira data URLs em base64 para arquivos privados ou arquivos gerados dentro da sua aplicação.
* Faça perguntas focadas e especifique o formato de saída que você quer.
* Para extração estruturada, combine file inputs com [respostas estruturadas](/guides/features/structured-responses).
## Solução de problemas
Garanta que o content da mensagem usa um array e inclui um bloco `type: "file"`. Se você usou uma URL, verifique se ela é publicamente acessível sem autenticação.
O arquivo pode estar extraindo uma grande quantidade de texto. Use um modelo com contexto maior, restrinja a tarefa, envie menos arquivos ou pré-extraia e corte o texto com a API Text Parser.
Dê a cada arquivo um `filename` descritivo e refira-se aos filenames diretamente no seu prompt. Por exemplo, "Compare `policy-v1.pdf` com `policy-v2.pdf`."
File inputs estão disponíveis em modelos de chat compatíveis. Verifique a [página de modelos](/models/overview) para conhecer as capacidades atuais e limites de contexto, ou tente um modelo de texto atual com contexto grande.