FlowModels

Escolha os modelos com precisão

FlowModels API

Use modelos de provedores liberados, com cobrança em euros. Gerencie o histórico você mesmo ou acrescente Brain, arquivos e memórias com um identificador de usuário final. As respostas estão disponíveis de forma síncrona, como stream e em segundo plano.

URL base
https://api.flowmodels.one/v1
Documento OpenAPI
openapi.json

Início rápido

Sem assinatura, pago pelo uso
O FlowModels não exige assinatura. Você paga pelo que usar e precisa de saldo ou de uma linha de crédito liberada. No painel do FlowModels, crie uma chave com a permissão “Usar IA” (kind: inference). “Gerenciar chaves” só permite administrar chaves de API. Mantenha as chaves secretas no seu próprio backend.

A interface certa

O FlowModels é uma API compatível com OpenAI, com chaves de API próprias e cobrança por uso em euros. Uma chave FlowModels pertence de forma permanente a este produto e a uma equipe de cobrança; external_identifier ativa opcionalmente o contexto do Brain e não muda o produto cobrado. Chaves de uma assinatura FlowSuite são separadas: as chamadas de modelo desta API as recusam com 403 insufficient_key_scope.

Prepare sua primeira requisição

  1. Abra o painel do FlowModels e crie ali uma chave com “Usar IA”. Donos de equipe têm acesso; outros membros precisam da própria permissão do FlowModels. Ao criar chaves pela API, é preciso definir kind: inference explicitamente; sem isso, a chave recebe “Gerenciar chaves” (kind: management).
  2. Recarregue pelo menos € 20 de saldo pré-pago ou use uma linha de crédito pós-paga liberada expressamente.
  3. Consulte GET /models e escolha um identificador completo de modelo.
  4. Envie model e suas mensagens, opcionalmente com external_identifier, a um dos dois endpoints a seguir para requisições de IA.
  5. Se você usar o Brain, guarde conversation da resposta. Sem o Brain, envie você mesmo o histórico necessário.

Onde esta API difere da OpenAI de propósito

Para Chat Completions e Responses, um cliente OpenAI existente pode, em geral, usar o endereço base do FlowModels. Considere as diferenças abaixo. A transcrição de arquivos e ao vivo tem um contrato próprio, com trabalhos, sessões e tíquetes de conexão.

  1. Cancelar é uma operação sem efeito bem-sucedida em qualquer estado final. POST /responses/{response_uuid}/cancel responde com o estado da resposta mesmo se ela já tiver terminado, falhado ou sido cancelada há muito tempo. A chamada pode portanto ser repetida sem chave de idempotência; o resultado depende do estado do trabalho, não do número de chamadas.
  2. Uma conexão interrompida não continua nada. Se a conexão cair durante uma requisição síncrona ou transmitida, não existe marcador de continuação: a requisição recomeça e é cobrada novamente. Os custos já gerados permanecem. Só um trabalho em segundo plano armazenado pode continuar a ser observado, com starting_after, e essa consulta não inicia uma nova chamada de modelo.
  3. A compressão do histórico é opcional. Se o histórico enviado não couber na janela de entrada do modelo, a requisição é recusada com 400 context_length_exceeded em vez de ser cortada em silêncio. Com context_compression: true você permite o resumo expressamente; ele é uma chamada de modelo adicional paga e é informado à parte em usage.flowai.compression.
  4. A busca na web fica desligada por padrão. web_search ativa a busca nativa do provedor e é cobrada à parte. Um modelo com busca integrada, por sua vez, recusa false em vez de executar a busca paga às escondidas.
  5. A busca pode ser limitada a domínios, e as fontes vêm junto. search_domain_filter aceita uma lista como ["firma.de"] (somente esses domínios) ou ["-reddit.com"] (exceto esses domínios) e ativa a busca. Quando o modelo pesquisou, a resposta traz citations com os endereços e search_results com title, url e date de cada fonte; em Chat Completions, no último chunk de um stream. Sem busca, os dois campos não aparecem.
  6. Sem valor, vale o máximo de tokens de saída do modelo. Nenhum valor padrão silencioso é usado, e um valor acima do máximo do modelo é recusado com 400 invalid_field_value, indicando esse máximo, em vez de ser reduzido.
  7. Os arquivos vão para o modelo escolhido, não para o Brain. Chat Completions e Responses aceitam file_id de POST /files, bytes diretos e URLs https. Imagens e vídeos só são vistos por um modelo que suporta o tipo, caso contrário 400 unsupported_for_model. Documentos que o modelo não lê por conta própria são extraídos como texto. Áudio que o modelo não escuta por conta própria é transcrito antes e cobrado à parte. Arquivos de usuários finais em /end_users continuam sendo documentos de texto. Bytes diretos são limitados a 8 MiB por requisição. Se o limite do proxy for menor, file_id e URLs continuam utilizáveis.

Autenticação

Use somente Authorization: Bearer $FLOWMODELS_API_KEY. Nem o identificador do usuário final nem a escolha do modelo substituem a autenticação. Requisições JSON precisam de Content-Type: application/json. Todos os caminhos desta página são relativos à URL base indicada acima. Apenas o gerenciamento de chaves em /api/user/api-keys não fica sob esta URL base, e sim em creativeskyline.de; os exemplos mostram o endereço completo.

Modelos

Escolha um modelo específico

GET /models retorna, para sua chave FlowModels, apenas modelos de provedores liberados e com preço. Escolha uma entrada com identificador completo no formato provider/model-id. Use o id dela sem alterações como model.

Os exemplos usam groq/openai/gpt-oss-120b como amostra. Antes de usar, confirme que esse identificador está na sua lista atual de modelos e, se necessário, troque-o. Disponibilidade, limites de contexto e formatos de arquivo suportados dependem do modelo.

Os preços estão em pricing.prompt e pricing.completion como valor em euros por milhão de tokens, com pricing.currency: EUR e pricing.unit: per_million_tokens. A API retorna strings decimais exatas; a visão geral de modelos arredonda a exibição para duas casas decimais. Esse arredondamento de exibição não altera a cobrança. Os preços incluem a margem aplicável à sua equipe. A visão geral de modelos no painel do FlowModels usa a mesma fonte de preços. A lista é paginada: com has_more: true, use o valor de last_id como after. O identificador do modelo pode conter outras barras.

Modelos de transcrição têm, em vez disso, transcription para capacidades e limites, além de pricing.unit: per_minute e pricing.variants para os modos e opções com preço. Esses modelos são chamados pelos endpoints de áudio. Preços de tokens de áudio e de texto podem aparecer também se o provedor cobrar por tokens reais.

Modelos de vídeo (kind video) têm, em vez disso, video para modo, duração, resoluções e opções, além de pricing.unit: per_second e pricing.variants para as combinações com preço de resolução, áudio e enable_thinking. Esses modelos são chamados pelos endpoints de vídeo.

Modelos de imagem (kind image) têm, em vez disso, image para tamanhos, qualidades e edição, além de pricing.unit: per_image e pricing.variants para as combinações com preço de tamanho e qualidade. Cada variante informa per_image, o preço de uma geração. Se o modelo puder editar (image.edits), ela traz também per_image_edit, o preço de uma edição via POST /images/edits, que pode ser maior por causa da imagem de referência. Esses modelos são chamados pelos endpoints de imagem.

O que uma entrada de modelo informa

kind diz para que o modelo serve: chat, embedding, image, video, audio, realtime ou other. Chat Completions e Responses aceitam apenas modelos com kind chat; qualquer outro modelo é recusado com 400 unsupported_for_model e param model antes de reservar saldo. Em modelos que não são de chat, todas as características em capabilities são false.

context_length é a janela de contexto do provedor, enquanto flowai_limits.input_tokens é o limite que o FlowModels realmente permite. Os dois valores podem diferir; o que conta para sua requisição é o menor em flowai_limits. Um valor null significa que nenhuma fonte informa o dado, e nunca “ilimitado”.

data_residency indica onde o provedor processa a requisição. eu significa que o modelo é operado em um data center na União Europeia, atualmente os modelos com o prefixo ionos/ (hospedados em Berlim). null significa que nenhuma garantia desse tipo é dada.

supported_parameters lista os campos de requisição que esse modelo realmente avalia, na grafia desta API. Um campo ausente ali é recusado com 400 unsupported_for_model em vez de ser descartado em silêncio. capabilities descreve a mesma informação como características, por exemplo se raciocínio, busca na web ou um esquema JSON nativo estão disponíveis; web_search_domain_filter_max informa quantos domínios search_domain_filter aceita, 0 significa sem filtro de domínio. Os dados brutos do provedor ficam sem alteração em provider_metadata; eles têm estrutura diferente por provedor e expressamente não são uma garantia.

GET /models/{model_id} retorna a mesma entrada isoladamente. O identificador é usado sem alterações, incluindo as barras que contiver. Identificadores desconhecidos e modelos sem preço cadastrado respondem igualmente com 404 model_not_found.

Quem escolhe o modelo é você, não o FlowModels

Com model você indica exatamente um modelo e, portanto, exatamente um provedor. O FlowModels não faz nenhuma escolha de modelo por conta própria: não há balanceamento automático de carga nem troca automática para outro modelo ou provedor. Se o provedor escolhido não responder ou recusar a requisição, você recebe o erro e decide se tenta de novo e com qual modelo.

GET
/v1/models

Listar modelos

Lista os modelos de provedores liberados e com preço para sua chave. O cursor é sempre o identificador completo do modelo.

Parâmetros de consulta

limit integer
Número de entradas de 1 a 100, padrão 100
after string
Identificador do modelo em last_id da página anterior
curl -X GET "https://api.flowmodels.one/v1/models" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/models/{model_id}

Consultar um modelo

Retorna uma única entrada de modelo com preços, capacidades e os limites do FlowModels que realmente se aplicam.

curl -X GET "https://api.flowmodels.one/v1/models/{model_id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Embeddings

Somente modelos de embedding listados

POST /embeddings gera vetores para seus próprios textos. Só podem ser usados os modelos de embedding liberados para isso, atualmente openai/text-embedding-3-small, openai/text-embedding-3-large e os modelos hospedados na UE ionos/BAAI/bge-m3 e ionos/Qwen/Qwen3-VL-Embedding-8B. Um modelo de linguagem é recusado com 400 unsupported_for_model antes de reservar saldo.

Comprimento do vetor

dimensions é opcional. ionos/BAAI/bge-m3 sempre retorna 1.024 valores; ali só é aceito 1024. ionos/Qwen/Qwen3-VL-Embedding-8B retorna 4.096 valores sem indicação e encurta para qualquer comprimento de 1 a 4.096. Um valor que o modelo não suporta é recusado com 400 unsupported_for_model e param dimensions antes de reservar saldo. Nos modelos da OpenAI, o provedor decide qual comprimento é permitido.

Uma entrada ou várias

input é uma string ou uma lista de strings. Um lote tem no máximo 2.048 entradas de no máximo 8.192 caracteres cada; se você exceder um dos limites, a requisição é recusada, não cortada. O lote inteiro é processado em uma única chamada ao provedor e cobrado uma vez. A ordem da resposta corresponde à ordem da sua entrada; index também a indica.

Lista de números ou Base64

Sem valor, você recebe os vetores como lista de números. Com encoding_format: base64 você recebe, em vez disso, a representação Base64 dos valores como números de ponto flutuante de 32 bits em ordem little-endian. Esse é o formato que os SDKs da OpenAI esperam, e ele transfere bem menos bytes. usage.cost e usage.currency informam o valor para o cliente final em euros, como em toda requisição paga.

POST
/v1/embeddings

Criar vetores

Cria vetores de embedding para uma string ou um lote de strings.

Corpo da requisição

model string
obrigatório
Identificador de um modelo de embedding liberado no formato provider/model-id
input string|array
obrigatório
Uma string ou até 2.048 strings de no máximo 8.192 caracteres cada
encoding_format string
float (padrão) ou base64 para Float32 little-endian
dimensions integer
Comprimento desejado do vetor, se o modelo suportar: bge-m3 somente 1024, Qwen3-VL-Embedding-8B de 1 a 4096
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos
curl -X POST "https://api.flowmodels.one/v1/embeddings" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/text-embedding-3-small", "input": ["Primeiro texto","Segundo texto"]}'

Rerank

Ordenar documentos por relevância

POST /rerank avalia o quanto cada um dos seus documentos corresponde a uma consulta e devolve os documentos ordenados por relevância, o mais relevante primeiro. O uso típico é a segunda etapa de uma busca: uma busca vetorial com POST /embeddings encontra candidatos, o rerank os ordena com mais precisão. Só pode ser usado o modelo hospedado na UE liberado para isso, ionos/Qwen/Qwen3-VL-Reranker-8B. Qualquer outro modelo é recusado com 400 unsupported_for_model antes de o crédito ser reservado. GET /models o lista como kind: rerank.

Requisição e limites

query é uma string não vazia de no máximo 8.192 caracteres, documents uma lista de 1 a 1.000 strings não vazias de no máximo 32.768 caracteres cada e no máximo 1.000.000 caracteres no total. O modelo avalia cada par de consulta e documento em uma janela de 32.768 tokens. Se você ultrapassar um limite, a requisição é recusada com 400 invalid_field_value, não truncada; param indica o campo. Imagens e outras partes de conteúdo não são suportadas em query e documents no momento.

Resposta

results contém uma entrada por documento com index, a posição na sua lista documents, e relevance_score, em ordem decrescente. Com top_n você recebe apenas as melhores entradas; 0 ou nenhum valor devolve todas. Um valor acima do número dos seus documentos é recusado com 400 invalid_field_value. Com return_documents: true cada entrada contém também document.text com o seu documento. model indica o identificador que você enviou.

Custos

Somente tokens de entrada são cobrados, ao preço por token indicado no catálogo; a saída é gratuita. Como o modelo avalia cada documento separadamente em relação à consulta, a consulta conta uma vez por documento, mais um modelo fixo de cerca de 66 tokens por par. usage.prompt_tokens indica os tokens cobrados, usage.cost e usage.currency o valor para o cliente final em euros. Um limite superior é reservado antes da chamada, o consumo real é debitado.

Códigos de erro

  • 400 invalid_field_value: O corpo viola um limite ou um formato, veja param.
  • 400 unsupported_for_model: O modelo não é um modelo de rerank liberado.
  • 429 insufficient_quota: O crédito ou o limite de gastos não é suficiente.
  • 503 provider_overloaded: O provedor está sobrecarregado, aguarde os segundos de Retry-After. O crédito não foi debitado.
  • 500 rerank_failed: Os documentos não puderam ser avaliados.
POST
/v1/rerank

Avaliar documentos

Avalia documentos pela relevância para uma consulta e os devolve em ordem decrescente.

Corpo da requisição

model string
obrigatório
Identificador de um modelo de rerank liberado no formato provider/model-id, atualmente ionos/Qwen/Qwen3-VL-Reranker-8B
query string
obrigatório
A consulta, não vazia, no máximo 8.192 caracteres
documents array
obrigatório
1 a 1.000 strings não vazias de no máximo 32.768 caracteres cada, no máximo 1.000.000 caracteres no total
top_n integer
Número dos melhores resultados, no máximo o número de documentos; 0 ou nenhum valor devolve todos
return_documents boolean
true adiciona document.text com o documento a cada resultado (padrão false)
curl -X POST "https://api.flowmodels.one/v1/rerank" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "ionos/Qwen/Qwen3-VL-Reranker-8B", "query": "Qual é a capital da Alemanha?", "documents": ["Paris é a capital da França.","Berlim é a capital da Alemanha."], "top_n": 1, "return_documents": true}'

Transcrever áudio

Escolha o modelo e as informações adicionais

Arquivos e áudio ao vivo usam endpoints próprios. Toda transcrição contém text, inclusive uma string vazia em caso de silêncio. timestamps fica desativado por padrão; marcações de tempo só aparecem em segments quando pedidas expressamente. No momento, nenhum modelo oferece identificação de falantes, por isso diarize=true é recusado. Opções e códigos de idioma não suportados são recusados com HTTP 422 antes da chamada paga ao provedor.

ModeloArquivoAo vivoInformações adicionais
groq/whisper-large-v3-turboSimNãoMarcações de tempo
groq/whisper-large-v3SimNãoMarcações de tempo
openai/gpt-transcribeSimNãoTexto
ionos/openai/whisper-large-v3SimNãoMarcações de tempo, hospedado na UE (Berlim)
openai/gpt-live-transcribeNãoSimTexto

A transcrição de arquivos e a ao vivo são liberadas separadamente. Use somente modelos da sua resposta atual de GET /models. Ali, transcription.modes, transcription.languages e os campos de opções descrevem as capacidades. pricing.variants traz as combinações disponíveis de modo e marcações de tempo, com preços em EUR por minuto e, quando aplicável, por milhão de tokens de áudio ou texto. Um preço ausente impede o início; não há troca automática de provedor.

Arquivos e trabalhos em segundo plano

Envie o arquivo como multipart/form-data diretamente para POST /audio/transcriptions. Um file_id enviado anteriormente não é aceito aqui. Os exemplos na área de código iniciam um trabalho em segundo plano. Omita background ou defina como false se quiser trabalhar de forma síncrona. Deixe o cabeçalho multipart, incluindo o boundary, por conta do seu cliente HTTP.

  • Síncrono: no máximo 24 MiB e dez minutos, HTTP 200 com o resultado.
  • Em segundo plano: background=true, em geral no máximo 200 MiB e oito horas, HTTP 202 com o ID do trabalho. Os limites do modelo também se aplicam.

Consulte GET /audio/transcriptions/{id} até status ter o valor completed, cancelled ou failed. Antes disso são possíveis queued e processing. progress fica entre 0 e 1. O resultado também contém model, usage, flowai_request_id e expires_at. Com marcações de tempo solicitadas, start e end se referem à gravação inteira, mesmo que ela seja processada em partes.

POST /audio/transcriptions/{id}/cancel impede novas partes; uma chamada ao provedor já paga ainda pode terminar. Em caso de erro ou cancelamento, pode haver resultados parciais confirmados. DELETE /audio/transcriptions/{id} exclui somente trabalhos concluídos. Gravações grandes do Groq, da OpenAI e da IONOS são divididas em partes limitadas e reagrupadas na ordem original.

Criar e conectar uma sessão ao vivo

POST /audio/transcription-sessions espera model e source: push para áudio do seu aplicativo ou url com um stream de áudio HTTP(S) público e direto em url. language, timestamps, diarize e max_seconds são opcionais. A duração padrão é de duas horas, a máxima de oito horas. É possível ter no máximo três sessões ativas por equipe ao mesmo tempo.

A resposta com HTTP 201 traz id, websocket_url, ticket e ticket_expires_at. O tíquete vale 60 segundos, está vinculado à sessão e é consumido uma única vez ao conectar. Envie-o como subprotocolo WebSocket flowai-ticket.TICKET. POST /audio/transcription-sessions/{id}/connection-ticket emite um novo tíquete e substitui o anterior. Chaves do FlowModels e dos provedores não entram na URL do WebSocket.

Aplicativos enviam frames binários em PCM16 little-endian, mono, 24 kHz. Isso equivale a 48.000 bytes por segundo. Cada frame deve conter um número par de bytes e no máximo 48.000 bytes; envie na velocidade de reprodução. Em fontes de URL, o servidor decodifica o áudio e o cliente recebe apenas eventos. Destinos em redes privadas, credenciais em URLs, playlists HLS e páginas de plataforma não são suportados. Streams MP4/M4A precisam de metadados antes dos dados de áudio ou de MP4 fragmentado; arquivos com metadados no final devem ir para o endpoint de arquivos.

Com {"type":"audio.commit"} você encerra um trecho de fala da OpenAI; o servidor faz isso no máximo a cada dez segundos de áudio. {"type":"session.stop"} ou POST /audio/transcription-sessions/{id}/stop encerra a gravação e processa os resultados pendentes. Os estados são waiting, running, stopping e, em seguida, completed ou failed.

Eventos e reconexão

  • session.ready: A conexão do cliente está pronta. O áudio pode ser armazenado brevemente em buffer durante o início do provedor.
  • transcript.partial: Substitua o rascunho anterior da mesma section_id por text. Estados intermediários não são armazenados de forma permanente.
  • transcript.final: Texto confirmado com id estável, sequence contínua e segments opcionais. Remova o rascunho correspondente e evite duplicatas usando o ID.
  • connection.interrupted: Interrupção com reason e audio_replayed:false.
  • usage: Duração de áudio até o momento e status de cobrança. O valor exato em EUR vem da chamada REST.
  • session.completed: Encerramento com status, eventualmente error, e a duração do áudio.

Guarde o último número de sequência confirmado. Após uma reconexão do cliente, consulte GET /audio/transcription-sessions/{id}?after_sequence=N. Cada página contém no máximo 1.000 trechos confirmados; siga next_after_sequence até last_sequence. text contém o texto dessa página. Eventos WebSocket e a chamada REST podem se sobrepor, por isso você precisa eliminar duplicatas por ID.

Você pode reconectar uma conexão push interrompida em até 30 segundos com um novo tíquete; depois disso, a gravação é encerrada. Conexões da OpenAI são renovadas de forma controlada após 50 minutos. A ordem dos trechos e a posição na gravação são preservadas. Áudio processado com resultado incerto não é reenviado automaticamente de forma paga. Áudio ainda não enviado fica em buffer por no máximo cinco segundos; ao exceder esse limite, a sessão é encerrada de forma controlada.

Observar um stream de áudio direto

Este exemplo roda com Node.js 22 ou superior. Defina FLOWMODELS_BASE_URL, FLOWMODELS_API_KEY e FLOWMODELS_AUDIO_URL no seu backend. Ele observa o stream por 30 segundos e depois solicita o encerramento.

const response = await fetch(`${process.env.FLOWMODELS_BASE_URL}/audio/transcription-sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FLOWMODELS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-live-transcribe', source: 'url',
    url: process.env.FLOWMODELS_AUDIO_URL, language: 'de',
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const session = await response.json();
const socket = new WebSocket(session.websocket_url, [`flowai-ticket.${session.ticket}`]);
let timer;
socket.addEventListener('open', () => {
  timer = setTimeout(() => socket.send(JSON.stringify({type: 'session.stop'})), 30000);
});
socket.addEventListener('message', ({data}) => {
  const event = JSON.parse(data);
  console.log(event);
  if (event.type === 'session.completed') socket.close();
});
socket.addEventListener('close', () => clearTimeout(timer));
socket.addEventListener('error', () => console.error('WebSocket connection failed'));

Cobrança, retenção e erros

Trabalhos de arquivo reservam o custo total estimado antes da primeira chamada ao provedor. Sessões ao vivo reservam primeiro 60 segundos e ampliam a reserva antes de transmitir mais áudio. Os preços dependem do modelo, do modo arquivo ou ao vivo e de opções adicionais pagas. O silêncio também pode ser cobrado; o Groq cobra no mínimo dez segundos por chamada ao provedor, também por parte de arquivo. Os tokens reais informados pelo provedor são considerados. usage.cost e usage.cost_micro_eur mostram os custos cobrados, não as reservas ainda abertas.

Use um Idempotency-Key na criação e, diante de uma resposta incerta, repita a mesma requisição com a mesma chave. Uma renovação de tíquete recebe uma nova chave de idempotência. Saldo, bloqueios de chave e limites de equipe também valem durante o processamento. Erros incertos do provedor podem deixar uma reserva aberta até o consumo ser esclarecido.

Os resultados prontos ficam disponíveis por 24 horas após a conclusão. expires_at descreve esse período de retenção; ticket_expires_at, apenas a validade do tíquete. Uploads e arquivos de trabalho são excluídos após a conclusão, o cancelamento ou um erro. Você exclui sessões ao vivo concluídas com DELETE /audio/transcription-sessions/{id}.

Erros típicos: HTTP 422 para opções, limites ou fontes inadequados; HTTP 429 para sessões paralelas demais; HTTP 503 com audio_disabled, audio_model_unavailable ou audio_pricing_unavailable quando a função, o modelo ou o preço não estão disponíveis. Um upgrade de WebSocket com tíquete inválido, expirado ou já usado é recusado. Em trabalhos e sessões aceitos, verifique também status e error; uma consulta de status bem-sucedida ainda não significa uma transcrição bem-sucedida.

Disponibilidade da transcrição ao vivo

A transcrição ao vivo é liberada separadamente e só está disponível para modelos que GET /models lista com o valor live em transcription.modes. A tabela acima mostra qual modo um modelo sabe operar em geral; o que vale para sua integração é a sua lista atual de modelos.

POST
/v1/audio/transcriptions

Transcrever um arquivo

Transcrever um arquivo. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

Corpo da requisição

model string
obrigatório
Identificador liberado provider/model-id de GET /models
language string
Código de idioma dependente do modelo, por exemplo de
timestamps boolean
Ativar marcações de tempo explicitamente; padrão false
diarize boolean
Identificação de falantes; nenhum modelo oferece isso no momento, por isso true é recusado com HTTP 422. Padrão false
file file
obrigatório
Arquivo de áudio, no máximo 200 MiB e oito horas; observe os limites do modelo
background boolean
Obrigatório acima de 24 MiB ou dez minutos. Resposta 202 com o ID do trabalho.
curl --fail-with-body "https://api.flowmodels.one/v1/audio/transcriptions" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -F 'model=groq/whisper-large-v3-turbo' \
  -F 'language=de' \
  -F 'background=true' \
  -F 'file=@recording.wav'
GET
/v1/audio/transcriptions/{id}

Consultar um trabalho

Consultar um trabalho. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X GET "https://api.flowmodels.one/v1/audio/transcriptions/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/audio/transcriptions/{id}/cancel

Cancelar um trabalho

Cancelar um trabalho. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X POST "https://api.flowmodels.one/v1/audio/transcriptions/{id}/cancel" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/audio/transcriptions/{id}

Excluir um trabalho concluído

Excluir um trabalho concluído. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X DELETE "https://api.flowmodels.one/v1/audio/transcriptions/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/audio/transcription-sessions

Criar uma sessão ao vivo

Criar uma sessão ao vivo. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

Corpo da requisição

model string
obrigatório
Identificador liberado provider/model-id de GET /models
language string
Código de idioma dependente do modelo, por exemplo de
timestamps boolean
Ativar marcações de tempo explicitamente; padrão false
diarize boolean
Identificação de falantes; nenhum modelo oferece isso no momento, por isso true é recusado com HTTP 422. Padrão false
source string
obrigatório
push para aplicativos ou url para streams de áudio HTTP(S) diretos
url string
Obrigatório com source=url. Sem destinos privados, credenciais ou playlists HLS.
max_seconds integer
Padrão 7200, no máximo 28800 segundos
curl -X POST "https://api.flowmodels.one/v1/audio/transcription-sessions" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-live-transcribe", "source": "push", "language": "de"}'
GET
/v1/audio/transcription-sessions/{id}

Consultar sessão e trechos confirmados

Consultar sessão e trechos confirmados. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

Parâmetros de consulta

after_sequence integer
Consultar apenas trechos confirmados posteriores, no máximo 1000 por página
curl -X GET "https://api.flowmodels.one/v1/audio/transcription-sessions/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/audio/transcription-sessions/{id}/connection-ticket

Solicitar um novo tíquete de conexão

Solicitar um novo tíquete de conexão. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X POST "https://api.flowmodels.one/v1/audio/transcription-sessions/{id}/connection-ticket" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/audio/transcription-sessions/{id}/stop

Encerrar a gravação e finalizar os resultados

Encerrar a gravação e finalizar os resultados. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X POST "https://api.flowmodels.one/v1/audio/transcription-sessions/{id}/stop" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/audio/transcription-sessions/{id}

Excluir uma sessão concluída

Excluir uma sessão concluída. É necessária uma chave FlowModels. Os resultados ficam disponíveis por 24 horas após a conclusão.

curl -X DELETE "https://api.flowmodels.one/v1/audio/transcription-sessions/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Gerar vídeos

Modelos e parâmetros

Os vídeos são gerados em segundo plano. Você inicia um trabalho, recebe imediatamente 202 com um ID de trabalho e depois consulta o status ou deixa um webhook avisar você. Não há troca automática de modelo.

ModeloEntradaDuração (segundos)ResoluçãoProporçãoOutros campos
bytedance/seedance-2.5/text-to-videoPrompt4 a 30480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9generate_audio, output_format
bytedance/seedance-2.5/image-to-videoImagem, opcionalmente prompt e imagem final4 a 30480p, 720p, 1080pSegue a imagemgenerate_audio
minimax/h3/text-to-videoPrompt5 a 152Kauto, adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16aigc_watermark
minimax/h3/image-to-videoImagem e prompt, opcionalmente imagem final5 a 152KComo em texto para vídeoaigc_watermark
alibaba/wan-3.0/text-to-videoPrompt2 a 30480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, adaptivegenerate_audio, enable_thinking, seed
alibaba/wan-3.0/image-to-videoImagem e prompt, opcionalmente imagem final2 a 30480p, 720p, 1080pComo em texto para vídeogenerate_audio, enable_thinking, seed

Use apenas modelos da sua resposta atual de GET /models; um modelo ainda não liberado é recusado. Campos que um modelo não conhece e campos desconhecidos são recusados com 422 e param antes de qualquer reserva. Por exemplo, o Seedance de imagem para vídeo não aceita aspect_ratio nem output_format, e modelos sem faixa de áudio recusam generate_audio.

Enviar imagens

Modelos de imagem para vídeo precisam de uma imagem inicial, seja como image_url (endereço público https ou URL data:), seja como image_file_id de um arquivo desta equipe enviado por POST /files. São permitidos JPEG, PNG, WebP e GIF de até 10 MiB. Para a imagem final valem as mesmas regras, com end_image_url ou end_image_file_id. Um arquivo de outra equipe ou desconhecido é recusado com 422 video_input_invalid.

Fluxo e status

  1. POST /videos verifica os parâmetros, reserva o preço total dos segundos solicitados e responde com 202.
  2. status é primeiro queued, depois in_progress e, por fim, completed, failed ou cancelled. Consulte em intervalos de pelo menos cinco segundos ou use webhooks.
  3. Quando o vídeo fica pronto, a resposta contém content_url, content_type e size_bytes. GET /videos/{id}/content responde com 302 para uma URL de download válida por 15 minutos.
  4. O vídeo fica disponível por sete dias após a conclusão; depois disso, o arquivo e o trabalho são excluídos automaticamente. expires_at indica o momento exato. DELETE /videos/{id} exclui antes um trabalho encerrado.

POST /videos/{id}/cancel cancela um trabalho enquanto ele ainda não estiver em execução e libera a reserva. Se a geração já tiver começado, a API responde com 409 video_not_cancellable; o trabalho então vai até o fim e é cobrado. Se a API responder com 202, o cancelamento ainda está sendo executado; confira o resultado com GET /videos/{id}.

Custos e reserva

A cobrança é feita por segundo do vídeo pronto, ao preço da combinação escolhida de modelo, resolução, áudio e, se for o caso, enable_thinking. pricing.variants em GET /models informa o preço em euros por segundo de cada variante. O preço é fixado no início do trabalho e fica reservado até a conclusão. Só é cobrado um vídeo armazenado com sucesso por nós; trabalhos com falha, recusados e cancelados não custam nada. Se faltar preço para uma combinação, a API responde com 503 video_pricing_unavailable e não inicia nada.

Limites e códigos de erro

O número de vídeos ativos ao mesmo tempo depende do seu nível de limite de taxa: 3, 5, 10 ou 20 por equipe. Se o limite for excedido, a API responde com 429 video_concurrency_exceeded e Retry-After. Com o cabeçalho Idempotency-Key você pode repetir uma requisição com segurança após um erro de rede; nenhum segundo vídeo é criado.

  • 422 invalid_video_request: um campo não combina com o modelo, veja param.
  • 422 video_input_invalid: a imagem está ausente, é inválida ou grande demais.
  • 429 insufficient_quota, 429 spend_limit_exceeded: o crédito ou o limite de gastos não é suficiente.
  • 429 video_concurrency_exceeded: vídeos ativos demais.
  • 503 video_model_unavailable, 503 video_pricing_unavailable, 503 video_provider_unavailable: tente novamente mais tarde; o crédito não foi debitado.
  • 503 video_storage_unavailable: o vídeo não pôde ser excluído agora; o trabalho é mantido. Tente novamente mais tarde, veja Retry-After.
  • 404 video_not_found: ID de trabalho desconhecido ou de outra equipe.
  • 409 video_not_cancellable, 409 video_not_deletable, 409 video_not_ready: o status atual não permite a ação.

Um trabalho com status failed contém error.code, por exemplo video_generation_failed ou video_content_rejected. Os webhooks entregam os eventos video.completed, video.failed e video.cancelled; a entrega nunca contém o prompt.

POST
/v1/videos

Criar um vídeo

Criar um vídeo. É necessária uma chave FlowModels.

Corpo da requisição

model string
obrigatório
Identificador liberado de GET /models, por exemplo bytedance/seedance-2.5/text-to-video
prompt string
Obrigatório em todos os modelos de texto para vídeo e em MiniMax e Wan de imagem para vídeo, opcional no Seedance de imagem para vídeo. No máximo 7.000 caracteres.
image_url string
Obrigatório em imagem para vídeo, a menos que image_file_id esteja definido: URL https ou URL data:image/...;base64. JPEG, PNG, WebP ou GIF, no máximo 10 MiB.
image_file_id string
file_id de um arquivo de imagem enviado antes por esta equipe, em vez de image_url
end_image_url string
Imagem final, apenas em modelos de imagem para vídeo. Mesmos formatos de image_url.
end_image_file_id string
file_id da imagem final, em vez de end_image_url
duration integer
Duração em segundos, intervalo por modelo, veja a tabela. Padrão 5.
resolution string
Resolução por modelo, veja a tabela
aspect_ratio string
Proporção por modelo. O Seedance de imagem para vídeo recusa este campo.
generate_audio boolean
Gerar áudio. Apenas Seedance e Wan, padrão true.
output_format string
mp4 ou mov. Apenas Seedance de texto para vídeo.
enable_thinking boolean
Apenas Wan, padrão false. Tem preço próprio por segundo.
seed integer
Apenas Wan, de 0 a 2147483647
aigc_watermark boolean
Apenas MiniMax, padrão false
curl --fail-with-body "https://api.flowmodels.one/v1/videos" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"bytedance/seedance-2.5/text-to-video","prompt":"Um barco de papel em um lago calmo ao nascer do sol","duration":5,"resolution":"720p"}'

# Consultar o status até que status seja "completed", "failed" ou "cancelled"
curl --fail-with-body "https://api.flowmodels.one/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY"

# Baixar o vídeo pronto (302 para uma URL de download de curta duração)
curl -L --fail-with-body "https://api.flowmodels.one/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" -o video.mp4
GET
/v1/videos

Listar vídeos

Listar vídeos. É necessária uma chave FlowModels.

Parâmetros de consulta

limit integer
Entradas por página, padrão 20, no máximo 100
after string
last_id da página anterior
status string
queued, in_progress, completed, failed ou cancelled
curl -X GET "https://api.flowmodels.one/v1/videos" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/videos/{id}

Consultar um vídeo

Consultar um vídeo. É necessária uma chave FlowModels.

curl -X GET "https://api.flowmodels.one/v1/videos/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/videos/{id}/content

Baixar o vídeo pronto

Baixar o vídeo pronto. É necessária uma chave FlowModels.

curl -X GET "https://api.flowmodels.one/v1/videos/{id}/content" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/videos/{id}/cancel

Cancelar um vídeo

Cancelar um vídeo. É necessária uma chave FlowModels.

curl -X POST "https://api.flowmodels.one/v1/videos/{id}/cancel" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/videos/{id}

Excluir um vídeo

Excluir um vídeo. É necessária uma chave FlowModels.

curl -X DELETE "https://api.flowmodels.one/v1/videos/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Gerar imagens

Modelos e parâmetros

Uma imagem é criada dentro do pedido: você envia um prompt e recebe a imagem pronta na mesma resposta, normalmente após poucos segundos. Não há troca automática de modelo.

ModeloTamanhosQualidadeEdição
openai/gpt-image-2.6-sunburstsquare, portrait, landscape, 2klow, mediumSim
google/gemini-3.1-flash-imagesquare, portrait, landscape, 2kmediumNão
google/gemini-nano-banana-2.1square, portrait, landscape, 2kmediumNão
minimax/h3-imagesquare, portrait, landscape, 2kmediumSim
minimax/h3-image-highspeedsquare, portrait, landscape, 2kmediumSim
ionos/black-forest-labs/FLUX.2-klein-4Bsquare, portrait, landscape, 2kmediumSim

ionos/black-forest-labs/FLUX.2-klein-4B é executado no IONOS AI Model Hub em Berlim (GDPR, hospedado na UE). Segundo a IONOS, o modelo considera apenas os primeiros 256 tokens do prompt; um prompt mais longo é aceito, mas o restante não é reproduzido.

O ID anterior google/gemini-3.1-flash-image-preview continua sendo aceito. O Google desativou esse modelo de pré-visualização, por isso o pedido é gerado com google/gemini-3.1-flash-image e cobrado pelo preço dele; model na resposta informa esse modelo.

square é quadrado, portrait vertical, landscape horizontal e 2k um formato horizontal largo em resolução maior. Use apenas modelos da sua resposta atual de GET /models; ali, image indica os tamanhos, as qualidades e se o modelo pode editar. Campos que um modelo não conhece e campos desconhecidos são recusados com 422 e param antes de qualquer reserva.

Editar imagens

POST /images/edits recebe também uma imagem, como image_url (endereço https público ou URL data:) ou como image_file_id de um arquivo desta equipe enviado por POST /files. São permitidos JPEG, PNG e WebP até 10 MiB. Um arquivo alheio ou desconhecido é recusado com 422 image_input_invalid. Em ionos/black-forest-labs/FLUX.2-klein-4B, a imagem precisa ter pelo menos 64 pixels em cada lado e uma proporção não mais extrema que 8:1, caso contrário também é recusada com 422 image_input_invalid. O resultado sempre tem o tamanho escolhido.

Resposta e consulta

A resposta segue a estrutura da API de imagens da OpenAI: created e data com exatamente uma entrada. Com response_format url ela contém um endereço de download, com b64_json a própria imagem em Base64. Além disso há id, content_type, size_bytes, expires_at e usage. GET /images/{id}/content responde com 302 para uma URL de download válida por 15 minutos. A imagem fica disponível por sete dias e depois é excluída automaticamente. DELETE /images/{id} a exclui antes.

Custos e reserva

A cobrança é por imagem, ao preço da combinação escolhida de modelo, tamanho e qualidade. pricing.variants em GET /models informa o preço em euros por imagem de cada variante. O valor é reservado antes da geração e só é cobrado quando a imagem estiver armazenada conosco. Pedidos recusados e com falha não custam nada. Se faltar o preço de um modelo, a API responde com 503 image_pricing_unavailable e não gera nada.

Limites e códigos de erro

Uma geração ocupa uma das vagas de pedidos simultâneos do seu nível de limite. Com o cabeçalho Idempotency-Key você pode repetir um pedido com segurança após um erro de rede; não surge uma segunda imagem. Não há webhooks para imagens, porque a resposta contém a imagem pronta.

  • 422 invalid_image_request: Um campo não corresponde ao modelo, veja param.
  • 422 image_input_invalid: A imagem a editar falta, é inválida ou grande demais.
  • 422 image_request_rejected: O modelo recusou o pedido.
  • 422 image_content_rejected: A imagem foi recusada por causa do conteúdo.
  • 429 insufficient_quota, 429 spend_limit_exceeded: Saldo ou limite de gastos insuficiente.
  • 503 image_model_unavailable, 503 image_pricing_unavailable, 503 image_provider_unavailable: Tente novamente mais tarde; seu saldo não foi cobrado.
  • 404 image_not_found: ID de imagem desconhecido, expirado ou alheio.
  • 409 image_not_ready, 409 image_not_deletable: O estado atual não permite a ação.
POST
/v1/images/generations

Gerar uma imagem

Gerar uma imagem. É necessária uma chave FlowModels.

Corpo da requisição

model string
obrigatório
Identificador liberado de GET /models, por exemplo openai/gpt-image-2.6-sunburst
prompt string
obrigatório
Descrição da imagem, no máximo 4.000 caracteres
size string
square, portrait, landscape ou 2k. Padrão square.
quality string
low ou medium em openai/gpt-image-2.6-sunburst (padrão low), apenas medium em google/gemini-3.1-flash-image, google/gemini-nano-banana-2.1, minimax/h3-image, minimax/h3-image-highspeed e ionos/black-forest-labs/FLUX.2-klein-4B
n integer
Número de imagens, apenas 1 é permitido
response_format string
url (padrão) ou b64_json
curl -X POST "https://api.flowmodels.one/v1/images/generations" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-image-2.6-sunburst", "prompt": "Um barco de papel em um lago calmo ao nascer do sol", "size": "landscape", "quality": "low"}'
POST
/v1/images/edits

Editar uma imagem

Editar uma imagem. É necessária uma chave FlowModels.

Corpo da requisição

model string
obrigatório
Identificador liberado de GET /models, por exemplo openai/gpt-image-2.6-sunburst
prompt string
obrigatório
Descrição da imagem, no máximo 4.000 caracteres
size string
square, portrait, landscape ou 2k. Padrão square.
quality string
low ou medium em openai/gpt-image-2.6-sunburst (padrão low), apenas medium em google/gemini-3.1-flash-image, google/gemini-nano-banana-2.1, minimax/h3-image, minimax/h3-image-highspeed e ionos/black-forest-labs/FLUX.2-klein-4B
n integer
Número de imagens, apenas 1 é permitido
response_format string
url (padrão) ou b64_json
image_url string
Imagem a editar, a menos que image_file_id esteja definido: URL https ou URL data:image/...;base64. JPEG, PNG ou WebP, no máximo 10 MiB.
image_file_id string
file_id de um arquivo de imagem enviado antes por esta equipe, em vez de image_url
curl -X POST "https://api.flowmodels.one/v1/images/edits" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-image-2.6-sunburst", "prompt": "Mach daraus eine Nachtszene mit Laternen", "image_url": "https://example.com/boot.png"}'
GET
/v1/images/{id}

Consultar uma imagem

Consultar uma imagem. É necessária uma chave FlowModels.

curl -X GET "https://api.flowmodels.one/v1/images/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/images/{id}/content

Baixar a imagem

Baixar a imagem. É necessária uma chave FlowModels.

curl -X GET "https://api.flowmodels.one/v1/images/{id}/content" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/images/{id}

Excluir uma imagem

Excluir uma imagem. É necessária uma chave FlowModels.

curl -X DELETE "https://api.flowmodels.one/v1/images/{id}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Decisões

Perguntas tipadas em vez de texto livre

POST /decisions responde a perguntas nomeadas sobre um conteúdo comum com probabilidades em vez de texto corrido. O formato segue a Decisions API da OpenAI, então você pode reaproveitar uma integração existente. Há quatro tipos de pergunta:

  • predicate: sim ou não. Resposta probability de 0 a 1.
  • choice: uma de várias opções de choices. Resposta choice, probabilities por opção e confidence.
  • score: uma avaliação nos níveis de levels, do mais baixo ao mais alto. Resposta score (média ponderada pelas probabilidades dos níveis, a partir de 0), probabilities por nível e confidence.
  • box: somente TypeSafe Jev. Localiza o que foi descrito em uma imagem de input. Resposta box com top, bottom, left e right como frações da altura e da largura da imagem (0 a 1) e confidence (pode ser null).

As respostas em answers seguem a ordem das suas perguntas e trazem o name de cada pergunta. Se um modelo recusar uma pergunta, essa entrada tem type: refusal.

Modelos e capacidades

ModeloTipos de perguntaPerguntas por requisiçãoImagensLimite de texto
openai/decisions/gpt-6-lunapredicate, choice, score400SimVerificado pelo provedor
typesafe/jev-1.14.0predicate, choice, score, box100Sim, PNG e JPEG256.000 caracteres de entrada, 128.000 por pergunta
typesafe/jev-latestcomo jev-1.14.0100Sim, PNG e JPEGcomo jev-1.14.0

typesafe/jev-latest sempre aponta para o modelo Jev atual. openai/decisions/gpt-6-luna é o gpt-6-luna pela Decisions API da OpenAI; o modelo de chat de mesmo nome, openai/gpt-6-luna, não é afetado e não pode ser usado aqui. GET /models lista os três modelos de decisão como kind: decision, com as capacidades em decision. São permitidas até oito imagens por requisição, somando input e as instructions das perguntas. prompt_cache_key existe somente na OpenAI.

Verificação antes de qualquer reserva

Um corpo malformado é recusado com 400 invalid_field_value, um campo que o modelo escolhido não suporta (por exemplo box na OpenAI ou perguntas demais) com 422 unsupported_for_model. Nos dois casos param indica o caminho completo do campo, por exemplo questions.3.type. Campos desconhecidos são recusados, não ignorados.

Custos

Somente tokens de entrada são cobrados; a saída é gratuita. Na OpenAI, usage.input_tokens já inclui as leituras e gravações de cache de input_tokens_details; leituras de cache custam menos. pricing em GET /models informa os preços em euros por 1 milhão de tokens (input, cached_input, cache_write). Um limite superior é reservado antes da chamada e o consumo real é cobrado. Se o modelo não entregar uma resposta utilizável, a requisição não custa nada.

usage.cost (euros como string decimal) e usage.cost_micro_eur informam o valor cobrado, usage.cost_status o seu estado: settled quando o valor já foi lançado, pending quando o lançamento é concluído depois. Enquanto for pending, cost e cost_micro_eur são null; depois o valor final passa a constar em GET /usage.

Códigos de erro

  • 400 invalid_field_value: O corpo está malformado, veja param.
  • 404 model_not_found: O ID não é um modelo de decisão.
  • 413 payload_too_large, 415 invalid_content_type: Corpo grande demais ou não é JSON.
  • 422 unsupported_for_model: Um campo não combina com o modelo, veja param.
  • 422 decision_input_invalid: Uma imagem é inválida, inacessível ou está no formato errado.
  • 422 decision_request_rejected: O modelo recusou a requisição; nada foi cobrado.
  • 429 insufficient_quota, 429 spend_limit_exceeded: Crédito ou limite de gastos insuficiente.
  • 429 decision_provider_rate_limited: O provedor está sobrecarregado, aguarde os segundos de Retry-After.
  • 502 decision_provider_invalid_response, 503 decision_provider_unavailable, 503 decision_model_unavailable, 503 decision_pricing_unavailable: Tente novamente mais tarde; seu crédito não foi cobrado.
POST
/v1/decisions

Consultar decisões

Responder a perguntas tipadas sobre um conteúdo comum. É necessária uma chave FlowModels.

Corpo da requisição

model string
obrigatório
openai/decisions/gpt-6-luna, typesafe/jev-1.14.0 ou typesafe/jev-latest (veja GET /models, kind decision)
input string|array
obrigatório
Conteúdo comum a todas as perguntas: uma string ou uma lista de mensagens com role (user, developer, system) e content. Mensagens user aceitam as partes input_text, input_image (image_url como URL https ou data URL) e input_json (data); mensagens developer e system aceitam somente input_text.
questions array
obrigatório
1 a 400 perguntas (menos, conforme o modelo), cada uma com type (predicate, choice, score, box), name único e instructions (string ou lista de input_text e input_image). choice exige choices [{value, description}] com 2 a 255 entradas únicas, score exige levels [{label, description}] com 2 a 10 níveis do mais baixo ao mais alto. description é opcional nos dois; recomenda-se uma descrição curta.
prompt_cache_key string
somente openai/decisions/gpt-6-luna: chave que divide a reutilização do cache de prompt
curl -X POST "https://api.flowmodels.one/v1/decisions" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "typesafe/jev-latest", "input": "Mir wurde das Abo diesen Monat doppelt berechnet. Bitte erstattet den zweiten Betrag.", "questions": [{"type":"predicate","name":"doppelte_abbuchung","instructions":"Beschreibt die Nachricht eine doppelte Abbuchung?"},{"type":"choice","name":"abteilung","instructions":"Welche Abteilung ist zuständig?","choices":[{"value":"buchhaltung","description":"Zahlungen und Erstattungen"},{"value":"technik","description":"Fehler und Störungen"}]},{"type":"score","name":"dringlichkeit","instructions":"Wie dringend ist die Nachricht?","levels":[{"label":"Kann warten","description":"Keine Frist"},{"label":"Diese Woche","description":"Sollte bald bearbeitet werden"},{"label":"Heute","description":"Sofort bearbeiten"}]}]}'

Chat Completions

Gerencie o histórico você mesmo ou use o Brain
Sem external_identifier, o gerenciamento de contexto fica com o cliente. Com o identificador, o Brain acrescenta o histórico salvo, memórias e trechos relevantes de arquivos. As duas variantes suportam streaming.

Iniciar uma conversa

O exemplo a seguir faz uma chamada sem contexto salvo de usuário final. Substitua o token e escolha um modelo da sua lista atual. Para usar o Brain, envie também external_identifier como string JSON. O identificador completo do modelo e a chave FlowModels são os mesmos nas duas variantes.

Deixe o modelo chamar suas próprias funções

Você pode oferecer ao modelo suas próprias funções. O FlowModels não executa essas funções. O modelo decide qual função deve ser chamada com quais argumentos, você executa a chamada no seu próprio sistema e envia o resultado de volta no turno seguinte. O fluxo sempre consiste, portanto, em duas requisições cobradas.

Primeiro turno. Você envia tools e, opcionalmente, tool_choice:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "Como está o tempo em Berlim?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Clima atual de uma cidade.",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }]
}

A resposta traz finish_reason: "tool_calls", content: null e as chamadas desejadas. arguments é uma string com JSON, não um objeto:

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{"city":"Berlin"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Segundo turno sem Brain. Você envia o histórico anterior, a mensagem do modelo e seu resultado como mensagem com role: "tool". O tool_call_id precisa corresponder ao id da chamada, caso contrário a API responde com HTTP 400:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "user", "content": "Como está o tempo em Berlim?"},
    {"role": "assistant", "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "get_weather", "arguments": "{"city":"Berlin"}"}}]},
    {"role": "tool", "tool_call_id": "call_abc", "content": "12 graus, nublado"}
  ],
  "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}]
}

No streaming, as chamadas chegam em um chunk próprio imediatamente antes do chunk final: choices[0].delta.tool_calls contém a entrada completa, incluindo index, e o chunk final traz finish_reason: "tool_calls". No endpoint Responses, as chamadas aparecem como entradas do tipo function_call em output, e você responde no turno seguinte com uma entrada do tipo function_call_output.

Segundo turno com Brain. Envie o mesmo external_identifier, o UUID de conversation retornado e apenas o resultado da ferramenta. A chamada do assistente salva permanece no servidor, e tool_call_id é conferido com essa chamada salva. Reenviar todo o histórico antigo gera contexto duplicado.

flowai_tools controla outra coisa, a saber, as ferramentas do lado do servidor do FlowModels. Enviar os dois campos na mesma requisição é recusado com HTTP 400 e invalid_field_value.

Saída estruturada: o que os provedores aceitam

json_object e json_schema em capabilities informam o que um modelo suporta nativamente; se a capacidade faltar, a API responde com 400 unsupported_for_model. Modelos da Anthropic não informam nenhum dos dois; modelos da Perplexity, apenas json_schema. Em modelos Gemini, chaves fora do subconjunto de esquema suportado são filtradas. Se um provedor ainda recusar um esquema solicitado, por exemplo strict: true com um esquema inválido, a API responde com 400 invalid_field_value e param: response_format; o texto de erro do provedor não é repassado.

POST
/v1/chat/completions

Chat Completions

Envia mensagens a um modelo de provedor liberado. Sem identificador de usuário final, o cliente gerencia o histórico; com ele, o Brain acrescenta o contexto pessoal.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
messages array
obrigatório
Novas mensagens com role e content; pelo menos uma mensagem de usuário não vazia
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
max_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
stream boolean
true entrega chunks de Chat Completions como SSE; padrão false
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning_effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max. Sem valor, vale o padrão do provedor, então não surge nenhum orçamento de raciocínio que você não tenha pedido. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models; um nível não suportado é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Os campos json_object e json_schema de GET /models dizem o que o modelo suporta nativamente; sem a capacidade, a API responde HTTP 400 e unsupported_for_model em vez de devolver texto corrido em silêncio. Com json_object, o FlowModels adiciona uma breve indicação de JSON se a palavra json não aparecer em nenhuma mensagem, porque alguns provedores recusam o modo JSON sem isso. Com json_schema, vale strict: false se você não enviar strict. Se o provedor ainda assim recusar o esquema, a API responde HTTP 400, invalid_field_value e param response_format
tools array
Suas próprias funções no formato [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON Schema>}}]. No máximo 128 entradas, cada descrição com no máximo 65.536 caracteres, cada esquema com no máximo 65.536 bytes em JSON. O FlowModels não executa essas funções: o modelo responde com tool_calls, você executa a função no seu próprio sistema e envia o resultado de volta como mensagem com role "tool". Se um modelo aceita funções consta em tools de GET /models; sem a capacidade, a API responde HTTP 400 e unsupported_for_model. Combinar com flowai_tools não é permitido e é recusado com HTTP 400 e invalid_field_value
tool_choice string|object
Controla a escolha de ferramentas: "auto", "none", "required" ou {"type":"function","function":{"name":…}} para exatamente uma função. Só é permitido junto com tools, e a função indicada precisa existir em tools. Sem valor, vale o padrão do provedor
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
max_completion_tokens integer
A mesma definição que max_tokens, com o nome usado pela API Responses. Enviar os dois com valores diferentes é recusado
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -X POST "https://api.flowmodels.one/v1/chat/completions" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role":"user","content":"Resuma os benefícios de um planejamento de projeto claro."}], "max_tokens": 512, "stream": false}'
POST
/v1/chat/completions
SSE / streaming

Chat Completions como SSE

Envia mensagens a um modelo de provedor liberado. Sem identificador de usuário final, o cliente gerencia o histórico; com ele, o Brain acrescenta o contexto pessoal.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
messages array
obrigatório
Novas mensagens com role e content; pelo menos uma mensagem de usuário não vazia
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
max_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
stream boolean
true entrega chunks de Chat Completions como SSE; padrão false
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning_effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max. Sem valor, vale o padrão do provedor, então não surge nenhum orçamento de raciocínio que você não tenha pedido. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models; um nível não suportado é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Os campos json_object e json_schema de GET /models dizem o que o modelo suporta nativamente; sem a capacidade, a API responde HTTP 400 e unsupported_for_model em vez de devolver texto corrido em silêncio. Com json_object, o FlowModels adiciona uma breve indicação de JSON se a palavra json não aparecer em nenhuma mensagem, porque alguns provedores recusam o modo JSON sem isso. Com json_schema, vale strict: false se você não enviar strict. Se o provedor ainda assim recusar o esquema, a API responde HTTP 400, invalid_field_value e param response_format
tools array
Suas próprias funções no formato [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON Schema>}}]. No máximo 128 entradas, cada descrição com no máximo 65.536 caracteres, cada esquema com no máximo 65.536 bytes em JSON. O FlowModels não executa essas funções: o modelo responde com tool_calls, você executa a função no seu próprio sistema e envia o resultado de volta como mensagem com role "tool". Se um modelo aceita funções consta em tools de GET /models; sem a capacidade, a API responde HTTP 400 e unsupported_for_model. Combinar com flowai_tools não é permitido e é recusado com HTTP 400 e invalid_field_value
tool_choice string|object
Controla a escolha de ferramentas: "auto", "none", "required" ou {"type":"function","function":{"name":…}} para exatamente uma função. Só é permitido junto com tools, e a função indicada precisa existir em tools. Sem valor, vale o padrão do provedor
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
max_completion_tokens integer
A mesma definição que max_tokens, com o nome usado pela API Responses. Enviar os dois com valores diferentes é recusado
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -X POST "https://api.flowmodels.one/v1/chat/completions" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role":"user","content":"Resuma os benefícios de um planejamento de projeto claro."}], "max_tokens": 512, "stream": true}'

Responses

Escolha o modo de resposta

Texto simples vai em input; mensagens estruturadas também são possíveis. Leia o texto em output[].content[] com type: output_text. Sem nenhuma opção adicional, você recebe JSON de forma síncrona. stream: true entrega eventos SSE. background: true inicia um trabalho em segundo plano e responde com HTTP 202 sem streaming. As duas opções podem ser combinadas.

Retenção de respostas

Com store: true, a resposta e seus eventos ficam disponíveis por 24 horas após a conclusão. Em segundo plano, o armazenamento vem ativado por padrão; nos outros casos, desativado. background: true não pode ser combinado com store: false. Uma resposta não armazenada não pode ser consultada por GET após a conclusão. A retenção de respostas é separada do histórico permanente de conversas do Brain.

Polling e continuação de SSE

Consulte respostas armazenadas em GET /responses/{response_uuid}. Para eventos, use ?stream=true. Guarde o último sequence_number de um evento; com starting_after=N você recebe apenas eventos posteriores. Essa consulta não inicia uma nova chamada de modelo. O cursor é um inteiro não negativo e exige stream=true. Respostas expiradas, não armazenadas ou de terceiros retornam 404 response_not_found.

Um stream de observação interrompido não encerra um trabalho em segundo plano. Você pode observá-lo novamente ou cancelá-lo com POST /responses/{response_uuid}/cancel. Os custos já gerados permanecem. Para receber resultados por webhook, registre um destino e envie o UUID dele como webhook_endpoint_id.

POST
/v1/responses

Responses

Alternativa com input em vez de messages, síncrona, como SSE ou em segundo plano. Um identificador de usuário final acrescenta, opcionalmente, o contexto do Brain.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
input string|array
obrigatório
Nova mensagem de usuário como texto ou estrutura de mensagem suportada
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
stream boolean
Receber eventos de resposta como SSE; também combinável com background
background boolean
Executar em segundo plano; sem stream, segue HTTP 202 com o ID da resposta
store boolean
Manter a resposta e seus eventos recuperáveis por 24 horas após a conclusão; padrão true com background, caso contrário false
webhook_endpoint_id uuid
Destino de webhook registrado para um trabalho em segundo plano
max_output_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning.effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max, neste endpoint dentro do objeto reasoning em vez de reasoning_effort. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models. Sem valor, vale o padrão do provedor; um nível desconhecido para o modelo é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída como em Chat Completions: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. A resposta devolve esse formato em text.format com o esquema incorporado de forma plana; sem valor, a resposta não tem o campo text
text.format object
Grafia alternativa da API Responses da OpenAI, como os SDKs oficiais enviam: {"type":"json_object"} ou {"type":"json_schema","name":…,"schema":…,"strict":…} com esquema plano. Funciona exatamente como response_format. Enviar os dois campos é recusado com HTTP 400, assim como outras chaves em text, por exemplo verbosity
tools array
Suas próprias funções, na mesma grafia de Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. A resposta as devolve na grafia da API Responses, com name plano, mas você sempre envia a forma aninhada. O FlowModels não executa as funções
tool_choice string|object
Como em Chat Completions: "auto", "none", "required" ou um objeto indicando exatamente uma função. As duas grafias são aceitas, {"type":"function","name":…} e {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
metadata object
Até 16 pares de strings guardados com a resposta armazenada e devolvidos nela. Em Chat Completions o campo é recusado porque nada é armazenado ali
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -X POST "https://api.flowmodels.one/v1/responses" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "groq/openai/gpt-oss-120b", "external_identifier": "customer-42", "input": "Resuma os benefícios de um planejamento de projeto claro.", "max_output_tokens": 512}'
POST
/v1/responses
SSE / streaming

Responses como SSE

Alternativa com input em vez de messages, síncrona, como SSE ou em segundo plano. Um identificador de usuário final acrescenta, opcionalmente, o contexto do Brain.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
input string|array
obrigatório
Nova mensagem de usuário como texto ou estrutura de mensagem suportada
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
stream boolean
Receber eventos de resposta como SSE; também combinável com background
background boolean
Executar em segundo plano; sem stream, segue HTTP 202 com o ID da resposta
store boolean
Manter a resposta e seus eventos recuperáveis por 24 horas após a conclusão; padrão true com background, caso contrário false
webhook_endpoint_id uuid
Destino de webhook registrado para um trabalho em segundo plano
max_output_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning.effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max, neste endpoint dentro do objeto reasoning em vez de reasoning_effort. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models. Sem valor, vale o padrão do provedor; um nível desconhecido para o modelo é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída como em Chat Completions: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. A resposta devolve esse formato em text.format com o esquema incorporado de forma plana; sem valor, a resposta não tem o campo text
text.format object
Grafia alternativa da API Responses da OpenAI, como os SDKs oficiais enviam: {"type":"json_object"} ou {"type":"json_schema","name":…,"schema":…,"strict":…} com esquema plano. Funciona exatamente como response_format. Enviar os dois campos é recusado com HTTP 400, assim como outras chaves em text, por exemplo verbosity
tools array
Suas próprias funções, na mesma grafia de Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. A resposta as devolve na grafia da API Responses, com name plano, mas você sempre envia a forma aninhada. O FlowModels não executa as funções
tool_choice string|object
Como em Chat Completions: "auto", "none", "required" ou um objeto indicando exatamente uma função. As duas grafias são aceitas, {"type":"function","name":…} e {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
metadata object
Até 16 pares de strings guardados com a resposta armazenada e devolvidos nela. Em Chat Completions o campo é recusado porque nada é armazenado ali
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -N -X POST "https://api.flowmodels.one/v1/responses" -H "Authorization: Bearer $FLOWMODELS_API_KEY" -H "Accept: text/event-stream" -H "Content-Type: application/json" --data '{"model":"groq/openai/gpt-oss-120b","external_identifier":"customer-42","input":"Resuma os benefícios de um planejamento de projeto claro.","max_output_tokens":512,"stream":true,"store":true}'
POST
/v1/responses

Responses em segundo plano

Inicia um trabalho em segundo plano armazenado e responde com HTTP 202. Use o ID da resposta para polling, SSE e cancelamento.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
input string|array
obrigatório
Nova mensagem de usuário como texto ou estrutura de mensagem suportada
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
stream boolean
Receber eventos de resposta como SSE; também combinável com background
background boolean
Executar em segundo plano; sem stream, segue HTTP 202 com o ID da resposta
store boolean
Manter a resposta e seus eventos recuperáveis por 24 horas após a conclusão; padrão true com background, caso contrário false
webhook_endpoint_id uuid
Destino de webhook registrado para um trabalho em segundo plano
max_output_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning.effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max, neste endpoint dentro do objeto reasoning em vez de reasoning_effort. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models. Sem valor, vale o padrão do provedor; um nível desconhecido para o modelo é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída como em Chat Completions: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. A resposta devolve esse formato em text.format com o esquema incorporado de forma plana; sem valor, a resposta não tem o campo text
text.format object
Grafia alternativa da API Responses da OpenAI, como os SDKs oficiais enviam: {"type":"json_object"} ou {"type":"json_schema","name":…,"schema":…,"strict":…} com esquema plano. Funciona exatamente como response_format. Enviar os dois campos é recusado com HTTP 400, assim como outras chaves em text, por exemplo verbosity
tools array
Suas próprias funções, na mesma grafia de Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. A resposta as devolve na grafia da API Responses, com name plano, mas você sempre envia a forma aninhada. O FlowModels não executa as funções
tool_choice string|object
Como em Chat Completions: "auto", "none", "required" ou um objeto indicando exatamente uma função. As duas grafias são aceitas, {"type":"function","name":…} e {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
metadata object
Até 16 pares de strings guardados com a resposta armazenada e devolvidos nela. Em Chat Completions o campo é recusado porque nada é armazenado ali
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -X POST "https://api.flowmodels.one/v1/responses" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"model": "groq/openai/gpt-oss-120b", "external_identifier": "customer-42", "input": "Resuma os benefícios de um planejamento de projeto claro.", "max_output_tokens": 512, "background": true, "store": true}'
POST
/v1/responses
SSE / streaming

Observar um trabalho em segundo plano diretamente como SSE

Combina background e stream. O worker continua em execução se o stream de observação for interrompido.

Corpo da requisição

model string
obrigatório
Identificador completo de GET /models no formato provider/model-id
external_identifier string
Ativa o contexto do Brain para seu identificador estável de usuário final, de 1 a 255 caracteres, enviado no corpo JSON
input string|array
obrigatório
Nova mensagem de usuário como texto ou estrutura de mensagem suportada
conversation uuid
UUID da resposta anterior do mesmo usuário final; omita para uma nova conversa
stream boolean
Receber eventos de resposta como SSE; também combinável com background
background boolean
Executar em segundo plano; sem stream, segue HTTP 202 com o ID da resposta
store boolean
Manter a resposta e seus eventos recuperáveis por 24 horas após a conclusão; padrão true com background, caso contrário false
webhook_endpoint_id uuid
Destino de webhook registrado para um trabalho em segundo plano
max_output_tokens integer
Limite superior da saída, de 1 a 128.000. Sem valor, vale o máximo do modelo; se nenhum estiver registrado para o modelo, valem 4.096 tokens. null conta como sem valor. Modelos da OpenAI aceitam pelo menos 16 tokens; um valor menor é recusado com 400
context_compression boolean
Permite que o FlowModels resuma no servidor um histórico longo demais enviado por você; padrão false. Sem isso, um histórico longo demais é recusado com 400 context_length_exceeded em vez de ser cortado. O resumo é uma chamada de modelo adicional paga e é informado em usage.flowai.compression
reasoning.effort string
Profundidade de raciocínio do modelo: none, minimal, low, medium, high, xhigh ou max, neste endpoint dentro do objeto reasoning em vez de reasoning_effort. Os níveis que um modelo aceita estão em capabilities.reasoning_levels de GET /models. Sem valor, vale o padrão do provedor; um nível desconhecido para o modelo é recusado com HTTP 400 e unsupported_for_model
web_search boolean
Ativa a busca nativa na web do provedor. Desligada por padrão, porque cada busca é cobrada à parte. Modelos sem busca nativa recusam true; modelos com busca integrada (Perplexity, Groq Compound) recusam false, nos dois casos com HTTP 400 e unsupported_for_model. Os campos web_search e web_search_forced de GET /models são a referência
response_format object
Formato da saída como em Chat Completions: {"type":"text"}, {"type":"json_object"} ou {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. A resposta devolve esse formato em text.format com o esquema incorporado de forma plana; sem valor, a resposta não tem o campo text
text.format object
Grafia alternativa da API Responses da OpenAI, como os SDKs oficiais enviam: {"type":"json_object"} ou {"type":"json_schema","name":…,"schema":…,"strict":…} com esquema plano. Funciona exatamente como response_format. Enviar os dois campos é recusado com HTTP 400, assim como outras chaves em text, por exemplo verbosity
tools array
Suas próprias funções, na mesma grafia de Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. A resposta as devolve na grafia da API Responses, com name plano, mas você sempre envia a forma aninhada. O FlowModels não executa as funções
tool_choice string|object
Como em Chat Completions: "auto", "none", "required" ou um objeto indicando exatamente uma função. As duas grafias são aceitas, {"type":"function","name":…} e {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Permite ou proíbe várias chamadas de função em uma resposta. Só é permitido junto com tools. Nem todo modelo tem essa opção; parallel_tool_calls em GET /models é a referência, caso contrário a API responde HTTP 400 e unsupported_for_model
stream_options object
Aceita apenas include_usage e exige stream: true. Com include_usage: true, um chunk final informa o consumo da resposta transmitida
user string
Seu próprio identificador do usuário final que faz a chamada, para rastrear abusos, até 128 caracteres. Ele não substitui external_identifier e não ativa o contexto do Brain
metadata object
Até 16 pares de strings guardados com a resposta armazenada e devolvidos nela. Em Chat Completions o campo é recusado porque nada é armazenado ali
search_domain_filter array
Restringe a busca nativa na web a até 20 domínios, por exemplo ["empresa.com.br"], ou os exclui com um sinal de menos à frente, por exemplo ["-reddit.com"]. Ou apenas domínios permitidos, ou apenas exclusões; domínios sem https:// e sem caminho, subdomínios incluídos. O campo liga a busca na web e é cobrado à parte. Quantos domínios um modelo aceita consta em GET /models em capabilities.web_search_domain_filter_max (xAI 5, nos demais 20); modelos sem filtro de domínio, como o Gemini, recusam o campo com 400 unsupported_for_model
curl -N -X POST "https://api.flowmodels.one/v1/responses" -H "Authorization: Bearer $FLOWMODELS_API_KEY" -H "Accept: text/event-stream" -H "Content-Type: application/json" --data '{"model":"groq/openai/gpt-oss-120b","external_identifier":"customer-42","input":"Resuma os benefícios de um planejamento de projeto claro.","max_output_tokens":512,"stream":true,"store":true,"background":true}'
GET
/v1/responses/{response_uuid}

Consultar o status da resposta

Retorna uma resposta armazenada da mesma equipe dentro do período de retenção.

curl -X GET "https://api.flowmodels.one/v1/responses/{response_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/responses/{response_uuid}
SSE / streaming

Continuar o stream de eventos armazenado

Entrega somente eventos após o sequence_number armazenado, sem iniciar uma nova chamada de modelo.

Parâmetros de consulta

stream boolean
obrigatório
true para SSE
starting_after integer
Último sequence_number recebido; a partir de 0, cursor exclusivo
curl -N -X GET "https://api.flowmodels.one/v1/responses/{response_uuid}?stream=true&starting_after=4" -H "Authorization: Bearer $FLOWMODELS_API_KEY" -H "Accept: text/event-stream" -H "Content-Type: application/json"
POST
/v1/responses/{response_uuid}/cancel

Cancelar uma resposta

Solicita, de forma idempotente, o cancelamento de um trabalho em segundo plano e retorna seu estado atual.

curl -X POST "https://api.flowmodels.one/v1/responses/{response_uuid}/cancel" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Continuar conversas

Enviar o UUID da resposta anterior

Na próxima chamada, envie o mesmo external_identifier, o UUID de conversation retornado e somente as novas mensagens. O histórico existente é complementado no servidor. Se você reenviar todo o histórico antigo, gera contexto duplicado.

{
  "model": "groq/openai/gpt-oss-120b",
  "external_identifier": "customer-42",
  "conversation": "018f1234-5678-7abc-9def-0123456789ab",
  "messages": [{"role": "user", "content": "Dê-me três próximos passos concretos para isso."}]
}

Uma requisição sem conversation inicia uma nova conversa. Um UUID desconhecido ou pertencente a outro workspace ou usuário final retorna 404 conversation_not_found. Só uma chamada pode rodar por vez na mesma conversa; chamadas concorrentes recebem 409 conversation_in_progress.

Histórico, arquivos e memórias

O Brain acrescenta o histórico de conversa salvo e memórias e trechos de arquivos relevantes da mesma pessoa. O contexto é ajustado ao orçamento de tokens do modelo. Históricos longos são resumidos passo a passo; essas chamadas de modelo também fazem parte do consumo pago. Resumos com erro não substituem um estado salvo válido. Sem identificador de usuário final, o cliente gerencia o histórico e nenhum contexto pessoal do Brain é buscado.

Gerenciamento de usuários finais

Exclusão com obrigação de retenção
A exclusão remove os dados pessoais de trabalho. Linhas de cobrança e consumo são mantidas por motivos de retenção.

Identificador externo e UUID pública

external_identifier é sua própria string estável, por exemplo customer-42. Com ela você associa requisições, dentro do seu workspace, a um usuário final. Identificadores numéricos também precisam ser enviados como string JSON. A primeira chamada de inferência sem conversation cria automaticamente um usuário final desconhecido.

Com POST /end-users você pode criar ou resolver o usuário final antes. O id retornado é a UUID pública para os endpoints de gerenciamento e de arquivos. Essa UUID é diferente do seu identificador externo e da UUID de conversation.

Compressão do histórico

Com external_identifier, o histórico fica conosco. Quando ele ultrapassa a janela de entrada do modelo, resumimos os turnos mais antigos e salvamos esse resumo. Assim, cada turno é comprimido exatamente uma vez e pago exatamente uma vez. Um número fixo dos turnos salvos mais recentes permanece sempre literal; tudo o que vem antes chega ao modelo apenas pelo resumo. Nada se perde: um turno só deixa de ficar literal depois que o resumo o incorporou.

Sem external_identifier, o histórico é seu, e não resumimos nada por conta própria. Se o histórico enviado não couber na janela de entrada, respondemos com 400 context_length_exceeded; a mensagem indica max_input_tokens e estimated_input_tokens. Envie então menos mensagens ou defina context_compression: true, autorizando expressamente a compressão. Essa compressão é uma chamada de modelo adicional paga por requisição e aparece no bloco de resposta usage.flowai.compression com calls, input_tokens, output_tokens e cost_micro_eur. Sem compressão, o campo não existe.

Metadados e memórias automáticas

Os metadados têm no máximo 50 entradas, com chaves de até 64 caracteres e strings de até 1.000 caracteres ou null como valor. A extração automática de memórias vem ativada por padrão para novos usuários finais assim que você usa o Brain com external_identifier. Não é necessário nenhum consentimento adicional. Sem identificador externo, o Brain não é usado. Desative a extração, se necessário, com PATCH /end-users/{end_user_uuid} e memory_extraction_enabled: false. Configurações já desativadas expressamente são mantidas.

Excluir dados de usuários finais

DELETE /end-users/{end_user_uuid} remove os dados pessoais de trabalho dessa pessoa do uso da API. Objetos de arquivos privados são excluídos em seguida, em segundo plano; erros temporários de armazenamento são repetidos. deleted: true portanto não confirma que a exclusão física de todos os objetos já terminou. Dados de cobrança e consumo são mantidos. UUIDs desconhecidas e de terceiros recebem a mesma resposta, com 404 end_user_not_found.

Consultar o comprovante de exclusão

GET /end_users/{end_user_uuid}/erasures lista as exclusões desse identificador, GET /end_users/{end_user_uuid}/erasures/{run_uuid} retorna um único comprovante. Ambos continuam disponíveis após a exclusão, pois é justamente nesse momento que você precisa da prova. status indica o estado, requested_at o momento da sua solicitação e completed_at a conclusão ou null, enquanto objetos ainda estão sendo removidos em segundo plano.

manifest_summary.resources indica, por tipo de dado, a quantidade antes e depois da operação. O comprovante contém apenas números: nenhum texto, nome de arquivo ou identificador. Tipos de dados sem nome público não são informados.

GET
/v1/end-users

Listar usuários finais

Lista os usuários finais do workspace autenticado com cursor UUID.

Parâmetros de consulta

limit integer
Número de entradas de 1 a 100, padrão 100
after uuid
UUID em last_id da página anterior
curl -X GET "https://api.flowmodels.one/v1/end-users" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/end-users

Criar ou resolver um usuário final

Cria um usuário final a partir do seu identificador externo estável ou retorna o registro existente.

Corpo da requisição

external_identifier string
obrigatório
Seu identificador estável e não sensível para esse usuário final
metadata object
Metadados próprios opcionais
curl -X POST "https://api.flowmodels.one/v1/end-users" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "customer-42", "metadata": {"plan":"pro"}}'
GET
/v1/end-users/{end_user_uuid}

Consultar um usuário final

Retorna um usuário final pela UUID.

curl -X GET "https://api.flowmodels.one/v1/end-users/{end_user_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
PATCH
/v1/end-users/{end_user_uuid}

Alterar um usuário final

Acrescenta metadados ou altera a extração automática de memórias de um usuário final.

Corpo da requisição

metadata object
Metadados que são mesclados aos valores existentes
memory_extraction_enabled boolean
Ativa ou desativa a extração automática de memórias
curl -X PATCH "https://api.flowmodels.one/v1/end-users/{end_user_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"memory_extraction_enabled": false}'
DELETE
/v1/end-users/{end_user_uuid}

Excluir um usuário final

Exclui os dados pessoais de trabalho de um usuário final. Linhas de cobrança e consumo são mantidas.

curl -X DELETE "https://api.flowmodels.one/v1/end-users/{end_user_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/end_users/{end_user_uuid}/erasures

Listar exclusões

Lista os comprovantes de exclusão de um identificador de usuário final, também após a exclusão.

Parâmetros de consulta

limit integer
Entradas por página, de 1 a 100, padrão 20
after string
Cursor de last_id da página anterior
curl -X GET "https://api.flowmodels.one/v1/end_users/{end_user_uuid}/erasures" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/end_users/{end_user_uuid}/erasures/{run_uuid}

Consultar um comprovante de exclusão

Retorna um único comprovante de exclusão com datas e quantidades por tipo de dado.

curl -X GET "https://api.flowmodels.one/v1/end_users/{end_user_uuid}/erasures/{run_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Arquivos como contexto do usuário final

Associar documentos a uma pessoa

Crie ou resolva o usuário final com POST /end-users. Use a UUID pública dele em POST /end_users/{end_user_uuid}/files. Observe o sublinhado em end_users; o gerenciamento de usuários finais, por outro lado, usa end-users.

Envie o arquivo como multipart/form-data com purpose=user_data. São suportados PDF, DOCX, XLSX, TXT, Markdown e CSV. Os limites padrão são 32 MiB por arquivo, 100 arquivos por usuário final e 5 GiB por workspace. Em requisições multipart, seu cliente HTTP gera o content type incluindo o boundary.

O processamento ocorre em segundo plano

Um upload bem-sucedido responde com HTTP 201 e status: pending. Somente após a extração e a indexação os trechos correspondentes ficam disponíveis para requisições futuras do mesmo usuário final. O upload ainda não confirma que o arquivo já é contexto de conversa consultável. Erros temporários de processamento são repetidos; conteúdo ilegível pode falhar de forma definitiva.

Listar, verificar e remover individualmente

GET /end_users/{end_user_uuid}/files lista os arquivos dessa pessoa, do mais novo ao mais antigo, página por página com limit e after. status indica o estado do processamento. DELETE /end_users/{end_user_uuid}/files/{file_uuid} remove um único arquivo junto com os trechos de texto extraídos dele; não é mais necessário excluir a pessoa inteira. O ID de arquivo desse upload continua não fazendo parte do gerenciamento geral de /files.

Após a exclusão, resta uma entrada sem conteúdo, sem nome de arquivo e sem objeto, para que o armazenamento já usado continue cobrável. Ela não aparece em nenhuma lista. Arquivos desconhecidos, de outra pessoa ou de outro workspace recebem a mesma resposta, com 404 file_not_found.

POST
/v1/end_users/{end_user_uuid}/files

Enviar um arquivo do usuário final

Armazena um arquivo de texto para o usuário final e inicia seu processamento. Use multipart/form-data.

Corpo da requisição

file file
obrigatório
Arquivo de texto ou documento suportado, com nome de até 255 caracteres
purpose string
obrigatório
Valor obrigatório user_data; outras finalidades são recusadas
curl -X POST "https://api.flowmodels.one/v1/end_users/END_USER_UUID/files" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@profil.pdf" \
  -F "purpose=user_data"
GET
/v1/end_users/{end_user_uuid}/files

Listar arquivos

Lista os arquivos de um usuário final, do mais novo ao mais antigo.

Parâmetros de consulta

limit integer
Entradas por página, de 1 a 100, padrão 20
after string
Cursor de last_id da página anterior
curl -X GET "https://api.flowmodels.one/v1/end_users/{end_user_uuid}/files" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/end_users/{end_user_uuid}/files/{file_uuid}

Consultar um arquivo

Retorna os dados de um único arquivo, sem o conteúdo.

curl -X GET "https://api.flowmodels.one/v1/end_users/{end_user_uuid}/files/{file_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/end_users/{end_user_uuid}/files/{file_uuid}

Excluir um arquivo

Remove um único arquivo junto com os trechos de texto extraídos dele.

curl -X DELETE "https://api.flowmodels.one/v1/end_users/{end_user_uuid}/files/{file_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Arquivos do workspace

Enviar arquivos

Envie uploads como multipart/form-data. As finalidades permitidas são user_data e vision. Não há prazo automático de retenção; arquivos que não forem mais necessários precisam ser excluídos expressamente.

Metadados e conteúdo

A consulta individual retorna apenas metadados. Os bytes armazenados ficam disponíveis somente pelo endpoint de conteúdo separado.

POST
/v1/files

Enviar um arquivo

Armazena um arquivo para requisições futuras. Use multipart/form-data.

Corpo da requisição

file file
obrigatório
Arquivo a enviar
purpose string
obrigatório
user_data ou vision
curl -X POST "https://api.flowmodels.one/v1/files" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@analyse.pdf" \
  -F "purpose=user_data"
GET
/v1/files

Listar arquivos

Lista os arquivos do workspace com cursor estável.

Parâmetros de consulta

purpose string
Filtro: user_data ou vision
order string
Ordenação: asc ou desc
limit integer
Número de 1 a 100
after string
ID público do arquivo em last_id
curl -X GET "https://api.flowmodels.one/v1/files" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/files/{file_uuid}

Consultar metadados do arquivo

Retorna metadados, não o conteúdo do arquivo.

curl -X GET "https://api.flowmodels.one/v1/files/{file_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/files/{file_uuid}/content

Baixar o conteúdo do arquivo

Entrega os bytes armazenados como download com o tipo de mídia original.

curl -X GET "https://api.flowmodels.one/v1/files/{file_uuid}/content" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
DELETE
/v1/files/{file_uuid}

Excluir um arquivo

Exclui os bytes armazenados e seus metadados.

curl -X DELETE "https://api.flowmodels.one/v1/files/{file_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Memórias

Memórias por usuário final

Estes endpoints fazem parte da função Brain do FlowModels e exigem uma chave FlowModels.

Todas as chamadas vinculam uma memória a exatamente um usuário final por meio de external_identifier. Alterações usam revision para a detecção otimista de conflitos.

Listar ou buscar

GET /memories responde a duas perguntas sobre as mesmas entradas. Sem query, você recebe as memórias dessa pessoa em ordem cronológica decrescente, página por página com limit e after; esse caminho não chama nenhum modelo e não custa nada. Com query, roda a busca por similaridade, que gera o embedding do texto de busca e por isso conta como consumo pago.

Um resultado de busca é um ranking, não uma página: por isso, a busca retorna has_more: false e last_id: null e não oferece cursor. Um valor de after que não venha de uma página anterior é recusado com 400 invalid_cursor e nunca respondido com uma página vazia.

Contexto para respostas futuras

Memórias salvas são usadas como contexto relevante dentro do mesmo workspace e usuário final. Criar uma memória manualmente não exige a extração automática ativada. Guarde a revision retornada e envie-a ao alterar a memória. Em caso de 409 memory_revision_conflict, você precisa buscar o estado atual novamente e conciliar a alteração.

POST
/v1/memories

Criar uma memória

Salva uma memória pessoal para um usuário final.

Corpo da requisição

external_identifier string
obrigatório
Seu identificador externo estável do usuário final
text string
obrigatório
Texto não vazio de no máximo 10.000 caracteres
kind string
Tipo opcional da memória
curl -X POST "https://api.flowmodels.one/v1/memories" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "customer-42", "text": "Prefere resumos curtos.", "kind": "preference"}'
PATCH
/v1/memories/{memory_uuid}

Alterar uma memória

Altera uma memória se a revisão informada for a atual.

Corpo da requisição

external_identifier string
obrigatório
Seu identificador externo estável do usuário final
text string
obrigatório
Novo texto da memória
revision integer
obrigatório
Revisão atual, no mínimo 1
curl -X PATCH "https://api.flowmodels.one/v1/memories/{memory_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "customer-42", "text": "Prefere resumos curtos com três tópicos.", "revision": 1}'
DELETE
/v1/memories/{memory_uuid}

Excluir uma memória

Exclui uma memória do usuário final indicado.

Corpo da requisição

external_identifier string
obrigatório
Seu identificador externo estável do usuário final
curl -X DELETE "https://api.flowmodels.one/v1/memories/{memory_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "customer-42"}'

Webhooks

Secret visível apenas uma vez
O secret de assinatura é retornado apenas na criação. Guarde-o em local seguro e não o publique.

Destinos e assinaturas

Os destinos de webhook precisam ser endereços HTTPS acessíveis publicamente. A API verifica os endereços ao salvar e novamente antes de cada entrega. Registre pelo menos um tipo de evento suportado.

Verificar entregas

O histórico de entregas mostra status, tentativas e o tipo de erro. Os filtros de status permitidos são pending, delivered, failed e exhausted.

Tipos de evento suportados

Além dos quatro eventos de conclusão de um trabalho em segundo plano (response.completed, response.failed, response.cancelled, response.incomplete), você pode assinar outros quatro tipos: credit.threshold ao atingir um dos seus limites de alerta em euros (data.metric é balance_floor se o valor disponível tiver caído abaixo do limite, ou spend_month se o consumo mensal o tiver atingido; data.threshold_eur indica o limite como string decimal, por exemplo "50.00"), credit.topup_failed em caso de recarga com falha, webhook_endpoint.deactivated quando um destino é desligado após repetidas falhas, e webhook.test para a entrega de teste acionada por você. Para gerações de vídeo, há ainda video.completed, video.failed e video.cancelled. Toda entrega tem a mesma estrutura: id, type, created_at e data. webhook_endpoint.deactivated vai deliberadamente para todos os demais destinos ativos do workspace, nunca para o que acabou de ser desligado: ele acabou de provar que não consegue receber nada.

Trocar o secret sem lacuna de entregas

Na troca, o secret anterior continua válido até o momento em secondary_secret_expires_at. Nessa janela, o cabeçalho webhook-signature contém dois valores separados por espaço, no formato v1,<signature>, um por secret. Verifique todos os valores e aceite a entrega na primeira correspondência. Depois da janela, somente o novo secret assina. A troca do secret exige uma chave de gerenciamento; uma chave de inferência recebe 403 insufficient_key_scope.

Verificar a assinatura

Toda entrega traz os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. A assinatura é um HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{Body}, em Base64 com o prefixo v1,. O secret é uma sequência aleatória de 48 caracteres, sem prefixo. Use-o exatamente como você o recebeu: como texto, sem decodificar de Base64. Bibliotecas de Standard Webhooks decodificam secrets no formato whsec_ antes de verificar e por isso chegam a um resultado diferente. Portanto, calcule o HMAC você mesmo sobre o body sem alterações e compare em tempo constante.

POST
/v1/webhook_endpoints

Criar um webhook

Registra um destino HTTPS e retorna o secret de assinatura uma única vez.

Corpo da requisição

url string
obrigatório
Endereço HTTPS acessível publicamente, no máximo 2.048 caracteres
events array
obrigatório
Pelo menos um tipo de evento suportado
description string
Descrição opcional, no máximo 255 caracteres
curl -X POST "https://api.flowmodels.one/v1/webhook_endpoints" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "value", "events": [], "description": "value"}'
GET
/v1/webhook_endpoints

Listar webhooks

Lista os destinos de webhook do workspace sem secrets.

Parâmetros de consulta

limit integer
Número de 1 a 100
after uuid
UUID em last_id
curl -X GET "https://api.flowmodels.one/v1/webhook_endpoints" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/webhook_endpoints/{webhook_uuid}

Consultar um webhook

Retorna um destino de webhook sem o secret de assinatura.

curl -X GET "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
PATCH
/v1/webhook_endpoints/{webhook_uuid}

Alterar um webhook

Altera destino, eventos, descrição ou status de ativação.

Corpo da requisição

url string
Novo endereço HTTPS acessível publicamente
events array
Nova lista de tipos de evento suportados
description string
Nova descrição ou null
is_active boolean
Desativa ou reativa o destino
curl -X PATCH "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "value", "events": [], "description": "value", "is_active": true}'
DELETE
/v1/webhook_endpoints/{webhook_uuid}

Excluir um webhook

Exclui o destino e seu histórico de entregas.

curl -X DELETE "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/webhook_endpoints/{webhook_uuid}/deliveries

Listar entregas

Lista as tentativas de entrega com status e detalhes de erro.

Parâmetros de consulta

status string
pending, delivered, failed ou exhausted
limit integer
Número de 1 a 100
after uuid
UUID em last_id
curl -X GET "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}/deliveries" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/webhook_endpoints/{webhook_uuid}/test

Enviar uma entrega de teste

Coloca na fila uma entrega sintética do tipo webhook.test. O resultado aparece no histórico de entregas.

curl -X POST "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}/test" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/webhook_endpoints/{webhook_uuid}/rotate_secret

Trocar o secret

Gera um novo secret de assinatura e o retorna uma única vez. O secret anterior continua válido até o momento indicado.

curl -X POST "https://api.flowmodels.one/v1/webhook_endpoints/{webhook_uuid}/rotate_secret" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Cobrança e chaves de API

Saldo próprio em euros

O FlowModels não exige assinatura. Novas equipes começam com € 0 no modo pré-pago. Recarregue pelo menos € 20 no painel do FlowModels. O valor da recarga é o valor final, sem acréscimo de impostos. Os valores da conta vêm em micro-EUR inteiros: um milhão de micro-EUR equivale a um euro.

Antes do processamento pago, os recursos são reservados. Depois, cobra-se o consumo real, incluindo contexto de conversa, retrieval e resumos necessários. Use usage.cost e usage.currency para o valor ao cliente final em euros. Preços ausentes não devem ser interpretados como consumo gratuito.

Se o histórico de uma requisição tiver sido comprimido, usage.flowai.compression informa essa parcela à parte: calls o número de chamadas de resumo, input_tokens e output_tokens seus tokens e cost_micro_eur seu custo em micro-EUR inteiros. Esse valor já está incluído em usage.cost; é mostrado separadamente para que um valor inesperadamente alto possa ser explicado pela própria resposta. Sem compressão, o campo não aparece.

Atualmente não há taxa mensal adicional de armazenamento para arquivos salvos no Brain. O processamento pago de modelos, como embeddings e análise de imagens ao processar um arquivo, é cobrado como consumo de modelo. Os limites de tamanho de arquivo e de equipe continuam valendo.

Pós-pago somente após liberação

Somente a administração pode ativar o pós-pago. Na primeira liberação, vem predefinida uma linha de crédito de € 50; a administração pode alterar esse valor por equipe. O saldo é usado primeiro. A fatura mensal contém apenas o consumo ainda não coberto pelo saldo. Valores em aberto e reservas em andamento reduzem a linha de crédito utilizável.

Recarga automática

A recarga automática vem desligada por padrão. Ative-a expressamente no painel e escolha um cartão verificado pertencente à equipe. O limite de saldo é de pelo menos € 5 e o valor da recarga de pelo menos € 20. Você pode revogar a autorização a qualquer momento. Uma recarga não altera um limite mensal de chave.

Chaves e dados de consumo separados

Em FlowModels → Chaves de API, crie uma chave com a permissão “Usar IA” ou “Gerenciar chaves”. Essas chaves ficam atribuídas permanentemente ao FlowModels e a uma equipe de cobrança. Chaves existentes da FlowSuite não são convertidas. Uma chave com “Gerenciar chaves” só pode administrar chaves do mesmo produto em /api/user/api-keys no creativeskyline.de, não sob a URL base; sem kind explícito, também ali é criada uma chave com “Gerenciar chaves”. Chamadas de modelo exigem kind: inference.

GET /credits retorna a conta em EUR; available_micro_eur é o saldo disponível, spendable_micro_eur considera também a linha de crédito liberada. reserved_oldest_at indica o momento da reserva aberta mais antiga ou null; uma reserva muito antiga indica um caso de esclarecimento que a administração resolve. GET /key mostra a chave usada e seus limites. A visão geral de consumo mostra seus gastos com o FlowModels. As faturas estão em Faturas.

Analisar o consumo

GET /usage resume o consumo de um período. start e end são dias no formato YYYY-MM-DD; sem eles, são analisados os últimos 30 dias. group_by aceita day (padrão), model, api_key e end_user. requests conta requisições, não chamadas a provedores: uma requisição com resumo e retrieval continua sendo uma requisição. cost_micro_eur é o valor já cobrado do cliente final, em micro-EUR.

GET /usage/requests lista as requisições individuais, da mais nova à mais antiga, página por página com limit e after, com filtros por status, api_key, end_user e model. A lista contém horário, modelo, provedor, status, código de erro, duração, número de tokens e custo. Os textos da requisição e da resposta nunca fazem parte dessa informação; para isso existe o suporte. Os dois endpoints podem ser chamados com uma chave com “Gerenciar chaves”.

provider indica o provedor em que a requisição foi efetivamente cobrada, na mesma grafia da primeira parte do identificador do modelo. Chaves de uma assinatura FlowSuite não alcançam os dois endpoints de consumo; elas recebem 403 insufficient_key_scope.

GET
/v1/credits

Consultar o saldo

Retorna a conta independente em EUR da equipe autenticada, sem pagamento nem chamada de modelo.

curl -X GET "https://api.flowmodels.one/v1/credits" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/usage

Resumir o consumo

Resume requisições, tokens e custos de um período por dia, modelo, chave ou usuário final.

Parâmetros de consulta

start string
Primeiro dia no formato YYYY-MM-DD, padrão 29 dias antes de end
end string
Último dia no formato YYYY-MM-DD, padrão hoje
group_by string
day, model, api_key ou end_user; padrão day
curl -X GET "https://api.flowmodels.one/v1/usage" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/usage/requests

Listar requisições individuais

Lista requisições individuais com modelo, provedor, status, duração, número de tokens e custo, sem o texto da requisição ou da resposta.

Parâmetros de consulta

limit integer
Entradas por página, de 1 a 100, padrão 20
after string
Cursor de last_id da página anterior
status string
Somente requisições com este status
api_key string
UUID de uma chave do mesmo workspace
end_user string
Identificador externo do usuário final
model string
Identificador do modelo como enviado na requisição
curl -X GET "https://api.flowmodels.one/v1/usage/requests" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/key

Verificar a chave de API em uso

Retorna status, tipo de chave e limites de requisição aplicáveis à chave de API autenticada.

curl -X GET "https://api.flowmodels.one/v1/key" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
https://creativeskyline.de/api/user/api-keys

Listar chaves de API

Lista as chaves ativas do usuário autenticado no workspace autenticado. Os valores secretos dos tokens nunca são retornados.

curl -X GET "https://creativeskyline.de/api/user/api-keys" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
https://creativeskyline.de/api/user/api-keys

Criar uma chave de API

Cria uma chave no workspace autenticado e retorna o novo valor do token nesta resposta.

Corpo da requisição

name string
obrigatório
Nome de exibição, no máximo 255 caracteres
kind string
inference ou management; padrão management. Para requisições de modelo, informe inference expressamente
expires_at datetime
Data de expiração futura opcional
curl -X POST "https://creativeskyline.de/api/user/api-keys" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Produção FlowModels", "kind": "inference"}'
DELETE
https://creativeskyline.de/api/user/api-keys/{key_uuid}

Revogar uma chave de API

Revoga imediatamente uma chave adicional do workspace autenticado. Chaves pessoais só podem ser renovadas.

curl -X DELETE "https://creativeskyline.de/api/user/api-keys/{key_uuid}" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
PUT
https://creativeskyline.de/api/user/api-keys/{key_uuid}/regenerate

Renovar uma chave de API

Substitui o valor do token de uma chave no workspace autenticado. O período de transição configurado determina por quanto tempo o valor anterior continua válido.

curl -X PUT "https://creativeskyline.de/api/user/api-keys/{key_uuid}/regenerate" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"

Limites e tratamento de erros

Respeite os limites de requisição

Por padrão, as chaves FlowModels têm no máximo 4 MiB por requisição JSON, 1.000 mensagens, 1.000.000 caracteres por mensagem e 128 ferramentas em tools. As requisições por minuto e as requisições simultâneas dependem do nível de limite de taxa do workspace: 60 por minuto e 10 simultâneas no nível 1, 600 e 25 no nível 2 (a partir de € 5 pagos), 2.000 e 50 no nível 3 (a partir de € 100) e 6.000 e 100 no nível 4 (a partir de € 500). A subida de nível é automática; na cobrança por fatura, conta o consumo faturado. Outros limites de tokens, custos e mensais podem se aplicar independentemente. GET /key informa seu nível, o limite efetivo por minuto e o limite de requisições simultâneas; uma chave só pode reduzir seu limite por minuto. O nível sobe automaticamente e não cai por conta própria.

Respostas comuns

  • 400 invalid_field_value: Verifique o campo obrigatório, o valor ou o tipo de dado.
  • 400 unsupported_field: Um campo não é suportado no endpoint escolhido. Verifique a lista de parâmetros dele. Você recebe a mesma resposta para context_compression enquanto a compressão de histórico estiver desligada.
  • 400 context_length_exceeded: O histórico enviado não cabe na janela de entrada do modelo. A mensagem indica max_input_tokens e estimated_input_tokens; param é messages. Envie menos mensagens ou defina context_compression: true.
  • 401 invalid_api_key: O token está ausente, é inválido, expirou ou foi revogado.
  • 403 insufficient_key_scope: Use uma chave com “Usar IA”.
  • 403 account_suspended: O acesso ao FlowModels dessa conta está suspenso. Entre em contato com o suporte; tentar novamente não ajuda.
  • 404 model_not_found: Compare o identificador completo com a lista atual de modelos.
  • 404 conversation_not_found: Verifique o workspace, o identificador do usuário final e a UUID da conversa.
  • 409 conversation_in_progress: Aguarde a chamada anterior da mesma conversa.
  • 409 idempotency_key_in_progress: A requisição com essa chave de idempotência ainda está em execução, ou o resultado dela não é conhecido com certeza após uma falha.
  • 413 payload_too_large: Reduza a requisição JSON.
  • 422 idempotency_key_reuse: A mesma chave de idempotência foi usada para outros dados de requisição.
  • 429 rate_limit_exceeded: Respeite o tempo de espera informado.
  • 429 concurrent_requests_exceeded: Já estão em execução tantas requisições simultâneas quantas o nível do workspace permite. Envie menos requisições em paralelo e tente novamente após o tempo de espera de Retry-After.
  • 429 insufficient_quota: Verifique o saldo disponível.
  • 429 spend_limit_exceeded: O limite mensal da chave ou a linha de crédito liberada não é suficiente; uma recarga não altera o limite de uma chave.
  • 503 routing_unavailable: O FlowModels está temporariamente desligado. Respeite o tempo de espera do cabeçalho Retry-After; nenhum saldo é reservado e nenhum provedor é chamado.
  • 503 provider_overloaded: O provedor está sem capacidade no momento. Respeite o tempo de espera do cabeçalho Retry-After e repita a chamada depois.
  • 400 invalid_cursor: O cursor está ausente, vazio ou não pertence à lista chamada.
  • 400 unsupported_for_model: O campo é válido, mas o modelo escolhido não o aceita; param indica o campo. Os campos que um modelo aceita constam em GET /models.
  • 401 invalid_token_source: A chave não foi enviada por Authorization: Bearer.
  • 404 response_not_found: A resposta é desconhecida, expirou ou não foi armazenada.
  • 404 file_not_found: O arquivo é desconhecido ou não pertence a este workspace.
  • 404 memory_not_found: A memória ou o usuário final correspondente não foi encontrado.
  • 404 end_user_not_found: O usuário final é desconhecido ou não pertence a este workspace.
  • 404 webhook_endpoint_not_found: O destino do webhook é desconhecido ou não pertence a este workspace.
  • 409 memory_revision_conflict: A memória foi alterada nesse meio-tempo.
  • 410 model_deprecated: O modelo foi descontinuado e não pode mais ser chamado; escolha um modelo em GET /models.
  • 413 file_too_large: O arquivo excede o limite de upload.
  • 429 credit_balance_exhausted: O saldo não é suficiente para esta requisição; é necessária uma recarga.
  • 429 period_spend_limit_exceeded: O limite de gastos do mês civil seria excedido; apenas uma recarga não altera esse limite.
  • 502 routing_execution_failed: A requisição não pôde ser concluída, por exemplo porque o provedor escolhido não respondeu. O FlowModels não recorre a outro modelo; você decide se repete a requisição.
  • 503 pricing_unavailable: No momento, não há um preço confiável disponível para o modelo.

Repetir com segurança e associar erros

Para requisições POST repetidas, use um Idempotency-Key estável por operação lógica. Uma requisição JSON idêntica concluída com sucesso pode ser respondida novamente dentro da janela de retenção, por padrão 24 horas. Conteúdos ou nomes de arquivo alterados exigem uma nova chave. Após uma queda de conexão, pode já ter havido processamento pago; por isso, não troque automaticamente para uma nova chave.

Erros contêm error.message, error.type, error.code e, quando aplicável, error.param. Guarde o flowai_request_id da resposta para solicitações de suporte.

Retenção dos seus registros de chamada

Para cada chamada, armazenamos um registro com horário, modelo, número de tokens, duração, status e flowai_request_id. O conteúdo da requisição enviado e o texto da resposta também são mantidos para diagnóstico de suporte e excluídos automaticamente após 30 dias; o registro em si permanece por 400 dias como comprovante de consumo e cobrança. A pedido, desativamos totalmente o armazenamento de texto de requisição e resposta para o seu workspace; os registros passam então a conter apenas os dados técnicos mencionados. Sem esse conteúdo, porém, o suporte não consegue mais rastrear uma chamada relatada.

Nomes de campos estáveis

Por que alguns campos continuam dizendo “flowai”

O FlowModels teve outro nome de produto no passado. O nome mudou, as respostas da sua integração não. Nomes de campos, códigos de erro e nomes de protocolo são um contrato com o seu código: renomeá-los obrigaria toda integração existente a mudar ao mesmo tempo. Por isso, eles permanecem iguais em definitivo e mantêm a palavra flowai.

  • flowai_request_id: Identificador de uma requisição em toda resposta, por exemplo para solicitações de suporte.
  • usage.flowai.*: Dados adicionais de consumo, como usage.flowai.compression.
  • flowai_limits e flowai_tools: Nomes de campos em entradas de modelos e requisições.
  • error.code e error.type: Dados de erro legíveis por máquina. O texto em error.message pode mudar; o código e o tipo, não.
  • flowai-ticket.*: O subprotocolo WebSocket da transcrição ao vivo.

Pode confiar: esses nomes não mudam com o nome do produto.