Guias
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.
- 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.
Início rápido
1. Faça o upload do arquivo
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:
{
"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
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:
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:
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-datacom exatamente uma parte, chamadafile. Qualquer outra parte, incluindopurpose, é rejeitada cominvalid_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 enviapurpose, 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
{
"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 |
|---|---|
{"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
{
"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.
Geração de vídeos
O primeiro e o último quadro vão em frame_images:
{
"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:
{
"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_urlouaudio_urlcontém exatamente um dos camposfile_idouurl, e nenhum outro. - Um mesmo array pode misturar entradas que usam
file_idcom entradas que usamurl. - A geração de imagens e de vídeos aceita apenas arquivos que você enviou. Para reutilizar uma imagem gerada, passe a
urlde 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:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["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 |
|---|---|---|
| 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
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"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
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Exclua um arquivo
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"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 |
GET | /api/v1/files | Uma página de arquivos |
GET | /api/v1/files/{file_id} | O 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:
{
"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.
Relacionados
Precisa de ajuda?
- Para dúvidas sobre API, cobrança e conta, fale com o suporte.
- Converse com os desenvolvedores da Felo no Discord.
- Confira nosso registro de alterações.
- Precisa de preços por volume ou ajuda com compras? Fale com vendas.
- Construindo com um LLM? Leia o llms.txt.