Felo API PlatformFelo API Platform

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

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-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

EndpointTipos de arquivoModalidade de entrada exigidaCampo
POST /api/v1/messagesPDF, imagemfile, imagemessages[].content[]
POST /api/v1/responsesPDF, imagemfile, imageinput[].content[]
POST /api/v1/images/generationsImagemimageinput_references[]
POST /api/v1/videos/generationsImagemimageframe_images[]
POST /api/v1/videos/generationsImagem, MP4, áudioimage, video, audioinput_references[]
POST /api/v1/chat/completionsSem 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

ArquivoBloco 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

{
  "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_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:

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Para enviarinput_modalities precisa incluir
Um PDFfile
Uma imagemimage
Um MP4video
Um arquivo de áudioaudio

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

LimiteValor
Tamanho do upload100 MiB (104,857,600 bytes) por arquivo; arquivos vazios são rejeitados
Bytes referenciados por requisição a um modelo50,000,000 bytes no total
Referências por requisição a um modelo100
Tamanho do nome do arquivo255 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.

TipoFormatosPode ser referenciado em
PDFPDFMessages, Responses
ImagemPNG, JPEG, GIF, WebPMessages, Responses, geração de imagens, geração de vídeos
VídeoMP4Geração de vídeos
ÁudioMP3, WAV, FLAC, OGGGeração de vídeos
OfficeDOCX, XLSX, PPTXSomente armazenamento
TextoTexto UTF-8, armazenado como text/plainSomente 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étodoCaminhoRetorna
POST/api/v1/filesO objeto de arquivo
GET/api/v1/filesUma 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}/content400 file_not_downloadable

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

Objeto de arquivo

CampoTipoDescrição
idstringID do arquivo, com o prefixo felo_file_. Use-o como file_id
typestringSempre file
sourcestringupload para arquivos que você enviou, generated para saídas de modelos
filenamestringO nome enviado com o upload
mime_typestringTipo detectado pelo conteúdo
size_bytesintegerTamanho em bytes
created_atstringTimestamp UTC em ISO 8601
downloadablebooleanfalse para arquivos enviados

Requisição de upload

ParteObrigatórioDescrição
fileSimO 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âmetroPadrãoDescrição
limit100Tamanho da página, de 1 a 1000
cursorO valor de cursor da página anterior
after, after_idAliases de cursor. Envie apenas um dos três
orderascApenas asc é aceito
Campo da respostaTipoDescrição
dataarrayObjetos de arquivo, do mais antigo para o mais recente
first_idstring ou nullID do primeiro arquivo da página
last_idstring ou nullID do último arquivo da página
cursorstring ou nullValor a passar como cursor para a próxima página
has_morebooleanIndica 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:

HTTPerror.codeSignificado
400invalid_content_typeO corpo não é multipart/form-data
400invalid_fileNenhuma parte file, uma parte extra, um arquivo vazio ou conteúdo sem suporte
400invalid_filenameO nome do arquivo é longo demais ou contém um caractere não permitido
413file_too_largeO arquivo excede 100 MiB
400invalid_queryUm parâmetro de consulta sem suporte, ou order diferente de asc
400invalid_limitlimit está fora do intervalo de 1 a 1000
400invalid_cursorO cursor está malformado, ou mais de um cursor foi enviado
400file_not_downloadable/content foi requisitado
404file_not_foundO arquivo não existe, foi excluído ou pertence a outra conta
503file_storage_unavailableO armazenamento de arquivos está temporariamente indisponível; tente novamente mais tarde
503file_upload_expiredO upload não foi concluído a tempo; envie o arquivo novamente

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

HTTPerror.codeSignificado
400invalid_file_inputID malformado, file_id e url no mesmo localizador, ou mais de 100 referências
400unsupported_file_typeO tipo do arquivo não corresponde à posição, por exemplo um MP4 em um bloco de documento
400file_model_unsupportedO modelo não declara a modalidade de entrada exigida
400file_input_too_largeOs arquivos referenciados excedem 50,000,000 bytes no total
400file_protocol_unsupportedUm ID de arquivo foi enviado para Chat Completions
404file_not_foundO 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?