# Upload de arquivos

Envie um arquivo uma vez e faça referência a ele pelo ID em solicitações de Messages, Responses, geração de imagens e geração de vídeos.

Faça o upload de um arquivo uma vez e depois referencie-o pelo ID nas requisições a modelos. Isso substitui reenviar os mesmos bytes em base64 ou hospedar o arquivo em uma URL pública.

Um ID de arquivo funciona com Messages, Responses, geração de imagens e geração de vídeos. Não funciona com Chat Completions.

## Antes de começar

- Uma chave de API. Consulte [Autenticação](https://openapi.felo.ai/pt-BR/docs/authentication.md).
- A URL base `https://openapi.felo.ai`.
- Um modelo que aceite o tipo de arquivo que você pretende enviar. Consulte [Verifique o suporte do modelo](#verifique-o-suporte-do-modelo).

## Início rápido

### 1. Faça o upload do arquivo

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Um upload bem-sucedido retorna HTTP `200` com os metadados do arquivo:

```json
{
  "id": "felo_file_0179...",
  "type": "file",
  "source": "upload",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "created_at": "2026-11-10T02:25:41Z",
  "downloadable": false
}
```

Guarde o `id`. Trate-o como uma string opaca: não o monte nem o analise.

### 2. Referencie-o em uma requisição

```bash
curl "https://openapi.felo.ai/api/v1/responses" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_file", "file_id": "felo_file_0179..."},
          {"type": "input_text", "text": "Summarize the attached report."}
        ]
      }
    ]
  }'
```

As mesmas duas etapas em Python:

```python
import os

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def upload(path: str) -> str:
    with open(path, "rb") as file:
        response = requests.post(
            f"{BASE}/api/v1/files",
            headers=HEADERS,
            files={"file": file},
            timeout=300,
        )
    response.raise_for_status()
    return response.json()["id"]


file_id = upload("./report.pdf")

response = requests.post(
    f"{BASE}/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "gpt-5.5",
        "input": [
            {
                "role": "user",
                "content": [
                    {"type": "input_file", "file_id": file_id},
                    {"type": "input_text", "text": "Summarize the attached report."},
                ],
            }
        ],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

E em Node.js 20 ou posterior:

```javascript
import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };

async function upload(path) {
  const form = new FormData();
  form.append("file", await openAsBlob(path), basename(path));
  const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  return (await response.json()).id;
}

const fileId = await upload("./report.pdf");
```

### Regras de upload

- O corpo é `multipart/form-data` com exatamente uma parte, chamada `file`. Qualquer outra parte, incluindo `purpose`, é rejeitada com `invalid_file`.
- Deixe o seu cliente HTTP definir o `Content-Type`. Defini-lo manualmente remove o multipart boundary.
- Não acrescente parâmetros de consulta à URL de upload.
- Faça o upload via HTTP em vez de usar o helper Files de um SDK. O `files.create()` do SDK da OpenAI sempre envia `purpose`, então não consegue chamar este endpoint.
- Um upload que excede o tempo limite ou perde a conexão ainda pode ter sido armazenado. Liste seus arquivos antes de fazer o upload novamente.

## Onde um ID de arquivo pode ser usado

| Endpoint | Tipos de arquivo | Modalidade de entrada exigida | Campo |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, imagem | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, imagem | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Imagem | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Imagem | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Imagem, MP4, áudio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Sem suporte | | |

### Messages

```json
{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
        {"type": "text", "text": "Summarize the attached report."}
      ]
    }
  ]
}
```

Para uma imagem, use `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Arquivo | Bloco de conteúdo |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Imagem | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Um bloco que contém `file_id` não pode conter também uma URL ou dados em base64.

### Geração de imagens

```json
{
  "model": "gemini-3-pro-image",
  "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
  ]
}
```

O restante da requisição, a resposta `202` e a consulta da tarefa são descritos em [Geração de imagens](https://openapi.felo.ai/pt-BR/docs/guides/image-generation.md).

### Geração de vídeos

O primeiro e o último quadro vão em `frame_images`:

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "The camera slowly pushes in. Keep the colors and composition.",
  "duration": 5,
  "resolution": "720p",
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"file_id": "felo_file_0179..."}
    }
  ]
}
```

Adicione uma segunda entrada com `"frame_type": "last_frame"` para um quadro final. Um último quadro exige um primeiro quadro.

O material de referência vai em `input_references`. Cada entrada usa o localizador correspondente ao seu tipo de mídia:

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
    {"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
    {"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
  ]
}
```

As combinações que um modelo aceita dependem do modelo e do canal. `frame_images` e `input_references` não podem ser usados na mesma requisição.

### Regras dos localizadores

- Em requisições de imagem e de vídeo, cada objeto `image_url`, `video_url` ou `audio_url` contém exatamente um dos campos `file_id` ou `url`, e nenhum outro.
- Um mesmo array pode misturar entradas que usam `file_id` com entradas que usam `url`.
- A geração de imagens e de vídeos aceita apenas arquivos que você enviou. Para reutilizar uma imagem gerada, passe a `url` de saída dela.
- Uma requisição que referencia um arquivo não é movida para outro canal em caso de falha. Não tente novamente em outro canal sem verificar o erro.
- Mantenha o arquivo até que todas as tarefas que o referenciam cheguem a um estado terminal. Excluí-lo antes pode fazer a tarefa falhar.

## Verifique o suporte do modelo

Um arquivo armazenado não pode ser usado automaticamente com todos os modelos. O modelo precisa declarar a modalidade de entrada correspondente no catálogo público:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| Para enviar | `input_modalities` precisa incluir |
|---|---|
| Um PDF | `file` |
| Uma imagem | `image` |
| Um MP4 | `video` |
| Um arquivo de áudio | `audio` |

Uma lista vazia ou ausente significa que IDs de arquivo não estão habilitados para esse modelo. Nesse caso, a requisição falha com `file_model_unsupported`. Não deduza o suporte pelo nome do modelo.

## Limites

| Limite | Valor |
|---|---|
| Tamanho do upload | 100 MiB (104,857,600 bytes) por arquivo; arquivos vazios são rejeitados |
| Bytes referenciados por requisição a um modelo | 50,000,000 bytes no total |
| Referências por requisição a um modelo | 100 |
| Tamanho do nome do arquivo | 255 caracteres |

Referenciar o mesmo arquivo duas vezes conta duas vezes para os dois limites por requisição. Um arquivo entre 50 MB e 100 MiB pode ser enviado, mas não pode ser referenciado em uma requisição a um modelo. Um modelo ou canal pode aplicar um limite menor.

### Tipos de arquivo

O tipo é detectado pelo conteúdo do arquivo, não pela extensão nem pelo `Content-Type` da parte.

| Tipo | Formatos | Pode ser referenciado em |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Imagem | PNG, JPEG, GIF, WebP | Messages, Responses, geração de imagens, geração de vídeos |
| Vídeo | MP4 | Geração de vídeos |
| Áudio | MP3, WAV, FLAC, OGG | Geração de vídeos |
| Office | DOCX, XLSX, PPTX | Somente armazenamento |
| Texto | Texto UTF-8, armazenado como `text/plain` | Somente armazenamento |

Qualquer outro conteúdo é rejeitado com `invalid_file`.

### Nomes de arquivo

Um nome de arquivo não pode conter `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` nem caracteres de controle. `/` é permitido como separador, mas segmentos vazios, `.` e `..` não são.

## Gerencie arquivos

Os arquivos pertencem à sua conta. Todas as chaves de API da conta veem os mesmos arquivos; outras contas não podem usar seus IDs de arquivo.

### Liste arquivos

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "data": [
    {
      "id": "felo_file_0179...",
      "type": "file",
      "source": "upload",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "created_at": "2026-11-10T02:25:41Z",
      "downloadable": false
    }
  ],
  "first_id": "felo_file_0179...",
  "last_id": "felo_file_0179...",
  "cursor": "felo_file_0179...",
  "has_more": false
}
```

Os resultados são ordenados do mais antigo para o mais recente. Quando `has_more` for `true`, passe o `cursor` retornado para obter a próxima página. Não há busca nem filtro por tipo no servidor.

### Obtenha um arquivo

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### Exclua um arquivo

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"id": "felo_file_0179...", "type": "file_deleted"}
```

A exclusão tem efeito imediato e não pode ser desfeita. Um `503` significa que a exclusão não foi concluída; envie o `DELETE` novamente.

### Downloads

Arquivos enviados não podem ser baixados. `GET /api/v1/files/{file_id}/content` retorna `400 file_not_downloadable`, e o cabeçalho `Location` da resposta do upload aponta para os metadados do arquivo, não para os bytes dele. Mantenha sua própria cópia de tudo o que você enviar.

Para baixar mídia gerada, use as URLs assinadas em `outputs` da tarefa.

## Referência da API

Todos os endpoints usam `Authorization: Bearer YOUR_API_KEY`. Respostas bem-sucedidas são objetos JSON simples, sem envelope.

| Método | Caminho | Retorna |
|---|---|---|
| `POST` | `/api/v1/files` | O [objeto de arquivo](#objeto-de-arquivo) |
| `GET` | `/api/v1/files` | Uma [página de arquivos](#par-metros-de-listagem) |
| `GET` | `/api/v1/files/{file_id}` | O [objeto de arquivo](#objeto-de-arquivo) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` e o `GET` de um único arquivo rejeitam qualquer parâmetro de consulta com `invalid_query`.

### Objeto de arquivo

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | ID do arquivo, com o prefixo `felo_file_`. Use-o como `file_id` |
| `type` | string | Sempre `file` |
| `source` | string | `upload` para arquivos que você enviou, `generated` para saídas de modelos |
| `filename` | string | O nome enviado com o upload |
| `mime_type` | string | Tipo detectado pelo conteúdo |
| `size_bytes` | integer | Tamanho em bytes |
| `created_at` | string | Timestamp UTC em ISO 8601 |
| `downloadable` | boolean | `false` para arquivos enviados |

### Requisição de upload

| Parte | Obrigatório | Descrição |
|---|---|---|
| `file` | Sim | O arquivo, enviado como uma parte de arquivo de `multipart/form-data` com um nome de arquivo |

A resposta inclui um cabeçalho `Location` com a URL dos metadados do arquivo.

### Parâmetros de listagem

| Parâmetro | Padrão | Descrição |
|---|---|---|
| `limit` | `100` | Tamanho da página, de 1 a 1000 |
| `cursor` | | O valor de `cursor` da página anterior |
| `after`, `after_id` | | Aliases de `cursor`. Envie apenas um dos três |
| `order` | `asc` | Apenas `asc` é aceito |

| Campo da resposta | Tipo | Descrição |
|---|---|---|
| `data` | array | Objetos de arquivo, do mais antigo para o mais recente |
| `first_id` | string ou null | ID do primeiro arquivo da página |
| `last_id` | string ou null | ID do último arquivo da página |
| `cursor` | string ou null | Valor a passar como `cursor` para a próxima página |
| `has_more` | boolean | Indica se existe outra página |

## Erros

Os endpoints de Files, Responses e a geração de imagens e de vídeos usam o envelope de erro da OpenAI:

```json
{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}
```

`param` é `null` em erros dos endpoints de Files. Messages retorna o formato de erro da Anthropic, que não tem `error.code`. O request ID fica no cabeçalho de resposta `X-Request-Id`.

Erros ao enviar ou gerenciar arquivos:

| HTTP | `error.code` | Significado |
|---|---|---|
| 400 | `invalid_content_type` | O corpo não é `multipart/form-data` |
| 400 | `invalid_file` | Nenhuma parte `file`, uma parte extra, um arquivo vazio ou conteúdo sem suporte |
| 400 | `invalid_filename` | O nome do arquivo é longo demais ou contém um caractere não permitido |
| 413 | `file_too_large` | O arquivo excede 100 MiB |
| 400 | `invalid_query` | Um parâmetro de consulta sem suporte, ou `order` diferente de `asc` |
| 400 | `invalid_limit` | `limit` está fora do intervalo de 1 a 1000 |
| 400 | `invalid_cursor` | O cursor está malformado, ou mais de um cursor foi enviado |
| 400 | `file_not_downloadable` | `/content` foi requisitado |
| 404 | `file_not_found` | O arquivo não existe, foi excluído ou pertence a outra conta |
| 503 | `file_storage_unavailable` | O armazenamento de arquivos está temporariamente indisponível; tente novamente mais tarde |
| 503 | `file_upload_expired` | O upload não foi concluído a tempo; envie o arquivo novamente |

Erros ao referenciar um arquivo em uma requisição a um modelo:

| HTTP | `error.code` | Significado |
|---|---|---|
| 400 | `invalid_file_input` | ID malformado, `file_id` e `url` no mesmo localizador, ou mais de 100 referências |
| 400 | `unsupported_file_type` | O tipo do arquivo não corresponde à posição, por exemplo um MP4 em um bloco de documento |
| 400 | `file_model_unsupported` | O modelo não declara a modalidade de entrada exigida |
| 400 | `file_input_too_large` | Os arquivos referenciados excedem 50,000,000 bytes no total |
| 400 | `file_protocol_unsupported` | Um ID de arquivo foi enviado para Chat Completions |
| 404 | `file_not_found` | O arquivo não existe, foi excluído, pertence a outra conta ou é um arquivo gerado enviado para a geração de imagens ou de vídeos |

Na geração de imagens e de vídeos, um arquivo também pode falhar depois do `202`. Nesse caso, a tarefa termina como `failed` com um desses códigos em `error.code`.

Erros de autenticação, saldo e limite de taxa são descritos em [Erros, limites e novas tentativas](https://openapi.felo.ai/pt-BR/docs/guides/errors-and-limits.md).

## Relacionados

- [Protocolos e SDKs](https://openapi.felo.ai/pt-BR/docs/guides/protocols.md)
- [Geração de imagens](https://openapi.felo.ai/pt-BR/docs/guides/image-generation.md)
- [Tarefas assíncronas](https://openapi.felo.ai/pt-BR/docs/guides/async-tasks.md)
- [Referência da API de Modelo](https://openapi.felo.ai/pt-BR/docs/model-api)
