FlowModels

Choose your models precisely

FlowModels API

Use released provider models with billing in euros. Manage the history yourself, or add Brain, files and memories with an end-user identifier. Responses are available synchronously, as a stream and in the background.

Base URL
https://api.flowmodels.one/v1
OpenAPI document
openapi.json

Quickstart

No subscription, pay as you go
FlowModels does not require a subscription. You pay for what you use and need credit or an enabled credit line. In the FlowModels dashboard, create a key with the “Use AI” permission (kind: inference). “Manage keys” only allows managing API keys. Keep secret keys in your own backend.

The right interface

FlowModels is an OpenAI-compatible API with its own API keys and usage-based billing in euros. A FlowModels key belongs permanently to this product and to one billing team; external_identifier optionally enables Brain context and does not change the billing product. Keys from a FlowSuite subscription are separate: the model calls of this API reject them with 403 insufficient_key_scope.

Prepare your first request

  1. Open the FlowModels dashboard and create a key with “Use AI” there. Team owners have access; other members need their own FlowModels permission. When creating keys through the API, kind: inference must be set explicitly; without it the key gets “Manage keys” (kind: management).
  2. Top up at least €20 of prepaid credit, or use an explicitly granted postpaid credit line.
  3. Call GET /models and pick a full model identifier.
  4. Send model and your messages, optionally with external_identifier, to one of the two following endpoints for AI requests.
  5. If you use Brain, store conversation from the response. Without Brain, send the history you need yourself.

Where this API deliberately differs from OpenAI

For Chat Completions and Responses, an existing OpenAI client can generally use the FlowModels base address. Keep the following differences in mind. File and live transcription have their own contract with jobs, sessions and connection tickets.

  1. Cancelling is a successful no-op on any final state. POST /responses/{response_uuid}/cancel answers with the response state even if it has long finished, failed or already been cancelled. The call can therefore be repeated without an idempotency key; the result depends on the state of the job, not on the number of calls.
  2. A dropped connection does not resume anything. If the connection breaks during a synchronous or streamed request, there is no resume token: the request starts over and is billed again. Costs already incurred remain. Only a stored background job can be observed further, using starting_after, and that retrieval does not start a new model call.
  3. History compression is opt-in. If the history you send does not fit into the model's input window, the request is rejected with 400 context_length_exceeded instead of being truncated silently. With context_compression: true you explicitly allow the summary; it is an additional paid model call and is reported separately in usage.flowai.compression.
  4. Web search is off by default. web_search turns on the provider's native search and is billed additionally. A model with built-in search, conversely, rejects false instead of quietly running the paid search anyway.
  5. Search can be limited to domains, and the sources come along. search_domain_filter takes a list such as ["firma.de"] (only these domains) or ["-reddit.com"] (not these domains) and turns on the search. When the model has searched, the response contains citations with the addresses and search_results with title, url and date per source; for Chat Completions in the last chunk of a stream. Without search, both fields are absent.
  6. Without a value, the model's maximum output tokens apply. No silent default is used, and a value above the model's maximum is rejected with 400 invalid_field_value and this maximum named, rather than being truncated.
  7. Files go to the selected model, not to Brain. Chat Completions and Responses accept file_id from POST /files, direct bytes and https URLs. Images and videos are only seen by a model that supports the type, otherwise 400 unsupported_for_model. Documents the model does not read itself are extracted as text. Audio the model does not hear itself is transcribed beforehand and billed separately. End-user files under /end_users remain text documents. Direct bytes are limited to 8 MiB per request. If the proxy limit is lower, file_id and URLs remain usable.

Authentication

Use only Authorization: Bearer $FLOWMODELS_API_KEY. Neither the end-user identifier nor the model selection replaces authentication. JSON requests need Content-Type: application/json. All paths on this page are relative to the base URL above. Only key management under /api/user/api-keys is not below this base URL but on creativeskyline.de; its examples show the full address.

Models

Choose a specific model

GET /models returns only released, priced provider models for your FlowModels key. Pick an entry with a full identifier in the format provider/model-id. Use its id unchanged as model.

The examples use groq/openai/gpt-oss-120b as a sample. Before using it, check that this identifier is in your current model list and replace it if necessary. Availability, context limits and supported file formats depend on the model.

Prices are listed under pricing.prompt and pricing.completion as an amount in euros per million tokens, with pricing.currency: EUR and pricing.unit: per_million_tokens. The API returns exact decimal strings; the model overview rounds the display to two decimal places. This display rounding does not change billing. Prices include the margin applying to your team. The model overview in the FlowModels dashboard uses the same price source. The list is paginated: when has_more: true, use the value of last_id as after. The model identifier itself may contain further slashes.

Transcription models instead have transcription for capabilities and limits, plus pricing.unit: per_minute and pricing.variants for the priced modes and options. These models are called through the audio endpoints. Audio and text token prices may also be listed if the provider bills by actual tokens.

Video models (kind video) instead have video for mode, duration, resolutions and options, plus pricing.unit: per_second and pricing.variants for the priced combinations of resolution, audio and enable_thinking. These models are called through the video endpoints.

Image models (kind image) instead have image for sizes, qualities and editing, plus pricing.unit: per_image and pricing.variants for the priced combinations of size and quality. Each variant names per_image, the price of a generation. If the model can edit (image.edits), it also carries per_image_edit, the price of an edit through POST /images/edits, which can be higher because of the reference image. These models are called through the image endpoints.

What a model entry tells you

kind says what the model is meant for: chat, embedding, image, video, audio, realtime or other. Chat Completions and Responses accept only models with kind chat; any other model is rejected with 400 unsupported_for_model and param model before credit is reserved. For non-chat models, all features under capabilities are false.

context_length is the provider's context window, while flowai_limits.input_tokens is the limit FlowModels actually permits. The two values can differ; the smaller one from flowai_limits is what counts for your request. A value of null means no source specifies it, never “unlimited”.

data_residency states where the provider processes the request. eu means the model runs in a data centre inside the European Union, currently the models with the prefix ionos/ (hosted in Berlin). null means no such commitment is made.

supported_parameters names the request fields this model really evaluates, in the spelling of this API. A field missing from it is rejected with 400 unsupported_for_model instead of being silently dropped. capabilities describes the same information as features, for example whether reasoning, web search or a native JSON schema are available; web_search_domain_filter_max states how many domains search_domain_filter accepts, 0 means no domain filter. The provider's raw data is kept unchanged under provider_metadata; it is structured differently per provider and is explicitly not a promise.

GET /models/{model_id} returns the same entry individually. The identifier is used unchanged, including any slashes it contains. Unknown identifiers and models without a maintained price both answer 404 model_not_found.

You choose the model, not FlowModels

With model you name exactly one model and therefore exactly one provider. FlowModels makes no model choice of its own: there is no automatic load balancing and no automatic switch to another model or provider. If the selected provider does not respond or refuses, you get the error and decide yourself whether to try again and with which model.

GET
/v1/models

List models

Lists the released, priced provider models for your key. The cursor is always the full model identifier.

Query parameters

limit integer
Number of entries from 1 to 100, default 100
after string
Model identifier from last_id of the previous page
curl -X GET "https://api.flowmodels.one/v1/models" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/models/{model_id}

Retrieve a model

Returns a single model entry with prices, capabilities and the FlowModels limits that actually apply.

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

Embeddings

Only listed embedding models

POST /embeddings generates vectors for your own texts. Only the embedding models released for this purpose can be used, currently openai/text-embedding-3-small, openai/text-embedding-3-large and the EU-hosted models ionos/BAAI/bge-m3 and ionos/Qwen/Qwen3-VL-Embedding-8B. A language model is rejected with 400 unsupported_for_model before credit is reserved.

Vector length

dimensions is optional. ionos/BAAI/bge-m3 always returns 1,024 values; it only accepts 1024. ionos/Qwen/Qwen3-VL-Embedding-8B returns 4,096 values without a value and shortens to any length from 1 to 4,096. A value the model does not support is rejected with 400 unsupported_for_model and param dimensions before credit is reserved. For the OpenAI models the provider decides which length is allowed.

One input or many

input is either a string or a list of strings. A batch has at most 2,048 entries of at most 8,192 characters each; if you exceed either limit, the request is rejected, not truncated. The whole batch is processed in one provider call and billed once. The response order matches the order of your input; index states it as well.

Number list or Base64

Without a value you get the vectors as a list of numbers. With encoding_format: base64 you instead get the Base64 representation of the values as 32-bit floating-point numbers in little-endian order. This is the format the OpenAI SDKs expect, and it transfers considerably fewer bytes. usage.cost and usage.currency report the end-customer amount in euros, as for every other paid request.

POST
/v1/embeddings

Create vectors

Creates embedding vectors for a string or a batch of strings.

Request body

model string
required
Identifier of a released embedding model in the format provider/model-id
input string|array
required
A string or up to 2,048 strings of at most 8,192 characters each
encoding_format string
float (default) or base64 for little-endian Float32
dimensions integer
Desired vector length, if the model supports it: bge-m3 only 1024, Qwen3-VL-Embedding-8B 1 to 4096
user string
Your own identifier of the calling end user for abuse tracing
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": ["First text","Second text"]}'

Rerank

Order documents by relevance

POST /rerank scores how well each of your documents matches a query and returns the documents ordered by relevance, the most relevant first. A typical use is the second step of a search: a vector search with POST /embeddings finds candidates, rerank orders them more precisely. Only the EU-hosted model released for this purpose can be used, ionos/Qwen/Qwen3-VL-Reranker-8B. Any other model is rejected with 400 unsupported_for_model before credit is reserved. GET /models lists it as kind: rerank.

Request and limits

query is a non-empty string of at most 8,192 characters, documents a list of 1 to 1,000 non-empty strings of at most 32,768 characters each and at most 1,000,000 characters in total. The model scores every pair of query and document in a window of 32,768 tokens. If you exceed a limit, the request is rejected with 400 invalid_field_value, not truncated; param names the field. Images and other content parts are not supported in query and documents at the moment.

Response

results contains one entry per document with index, the position in your documents list, and relevance_score, sorted in descending order. With top_n you only get the best entries; 0 or no value returns all of them. A value above the number of your documents is rejected with 400 invalid_field_value. With return_documents: true every entry also contains document.text with your document. model names the identifier you sent.

Costs

Only input tokens are billed, at the per-token price shown in the catalogue; output is free. Because the model scores every document separately against the query, the query counts once per document, plus a fixed template of about 66 tokens per pair. usage.prompt_tokens states the billed tokens, usage.cost and usage.currency the end-customer amount in euros. An upper bound is reserved before the call, the actual usage is charged.

Error codes

  • 400 invalid_field_value: The body violates a limit or a format, see param.
  • 400 unsupported_for_model: The model is not a released rerank model.
  • 429 insufficient_quota: Credit or spending limit is not sufficient.
  • 503 provider_overloaded: The provider is overloaded, wait for the seconds in Retry-After. Your credit was not charged.
  • 500 rerank_failed: The documents could not be scored.
POST
/v1/rerank

Score documents

Scores documents by their relevance to a query and returns them in descending order.

Request body

model string
required
Identifier of a released rerank model in the format provider/model-id, currently ionos/Qwen/Qwen3-VL-Reranker-8B
query string
required
The query, not empty, at most 8,192 characters
documents array
required
1 to 1,000 non-empty strings of at most 32,768 characters each, at most 1,000,000 characters in total
top_n integer
Number of best results, at most the number of documents; 0 or no value returns all of them
return_documents boolean
true adds document.text with the document to every result (default 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": "What is the capital of Germany?", "documents": ["Paris is the capital of France.","Berlin is the capital of Germany."], "top_n": 1, "return_documents": true}'

Transcribe audio

Choose a model and extra information

Files and live audio use their own endpoints. Every transcript contains text, also an empty string for silence. timestamps is off by default; timestamps only appear in segments on explicit request. No model currently offers speaker labels, so diarize=true is rejected. Unsupported options and language codes are rejected with HTTP 422 before the paid provider call.

ModelFileLiveExtra information
groq/whisper-large-v3-turboYesNoTimestamps
groq/whisper-large-v3YesNoTimestamps
openai/gpt-transcribeYesNoText
ionos/openai/whisper-large-v3YesNoTimestamps, EU-hosted (Berlin)
openai/gpt-live-transcribeNoYesText

File and live transcription are enabled separately. Only use models from your current response to GET /models. There, transcription.modes, transcription.languages and the option fields describe the capabilities. pricing.variants lists the available combinations of mode and timestamps, with prices in EUR per minute and possibly per million audio or text tokens. A missing price prevents the start; there is no automatic switch of provider.

Files and background jobs

Send the file as multipart/form-data directly to POST /audio/transcriptions. A previously uploaded file_id is not accepted here. The examples in the code area start a background job. Omit background or set it to false if you want to work synchronously. Leave the multipart header including its boundary to your HTTP client.

  • Synchronous: at most 24 MiB and ten minutes, HTTP 200 with the result.
  • Background: background=true, in general at most 200 MiB and eight hours, HTTP 202 with a job ID. Model limits apply as well.

Poll GET /audio/transcriptions/{id} until status has the value completed, cancelled or failed. Before that, queued and processing are possible. progress is between 0 and 1. The result also contains model, usage, flowai_request_id and expires_at. For requested timestamps, start and end refer to the whole recording, even if it is processed in segments.

POST /audio/transcriptions/{id}/cancel prevents further segments; a provider call that has already been paid for may still finish. On an error or cancellation, confirmed partial results may be available. DELETE /audio/transcriptions/{id} only deletes completed jobs. Large Groq, OpenAI and IONOS recordings are split into limited segments and put back together in their original order.

Create and connect a live session

POST /audio/transcription-sessions expects model and source: push for audio from your app, or url with a direct public HTTP(S) audio stream in url. language, timestamps, diarize and max_seconds are optional. The default runtime is two hours, the maximum eight hours. At most three active sessions per team are possible at the same time.

The HTTP 201 response returns id, websocket_url, ticket and ticket_expires_at. The ticket is valid for 60 seconds, is bound to the session and is used up once when connecting. Pass it as the WebSocket subprotocol flowai-ticket.TICKET. POST /audio/transcription-sessions/{id}/connection-ticket issues a new ticket and replaces the previous one. FlowModels and provider keys do not belong in the WebSocket URL.

Apps send binary frames with PCM16 little-endian, mono, 24 kHz. That is 48,000 bytes per second. Every frame must contain an even number of bytes and at most 48,000 bytes; send at playback speed. For URL sources, the server decodes the audio and the client only receives events. Private network targets, credentials in URLs, HLS playlists and platform pages are not supported. MP4/M4A streams need metadata before the audio data or fragmented MP4; files with trailing metadata belong at the file endpoint.

With {"type":"audio.commit"} you complete an OpenAI speech segment; the server does this at the latest after every ten seconds of audio. {"type":"session.stop"} or POST /audio/transcription-sessions/{id}/stop ends the recording and processes pending results. The states are waiting, running, stopping and then completed or failed.

Events and reconnection

  • session.ready: The client connection is established. Audio may be buffered briefly during provider start-up.
  • transcript.partial: Replace the previous draft of the same section_id with text. Intermediate states are not stored permanently.
  • transcript.final: Confirmed text with a stable id, a continuous sequence and optional segments. Remove the corresponding draft and avoid duplicates using the ID.
  • connection.interrupted: Interruption with reason and audio_replayed:false.
  • usage: Audio duration so far and billing status. The exact EUR amount comes from the REST call.
  • session.completed: Completion with status, possibly error and the audio duration.

Store the last confirmed sequence number. After a client reconnect, call GET /audio/transcription-sessions/{id}?after_sequence=N. Each page contains at most 1,000 confirmed segments; follow next_after_sequence up to last_sequence. text contains the text of that page. WebSocket events and the REST call can overlap, so you have to deduplicate by ID.

You can reattach a dropped push connection with a new ticket within 30 seconds; after that the recording is ended. OpenAI connections are renewed in a controlled way after 50 minutes. Segment order and recording offset are preserved. Audio processed with an unclear outcome is not automatically sent again for a fee. Unsent audio is buffered for at most five seconds; beyond that, the session ends in a controlled way.

Observe a direct audio stream

This example runs with Node.js 22 or later. Set FLOWMODELS_BASE_URL, FLOWMODELS_API_KEY and FLOWMODELS_AUDIO_URL in your backend. It observes the stream for 30 seconds and then requests completion.

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'));

Billing, retention and errors

File jobs reserve the estimated total cost before the first provider call. Live sessions first reserve 60 seconds and extend the reservation before further audio is transferred. Prices depend on the model, file or live mode and paid add-on options. Silence can also incur costs; Groq bills at least ten seconds per provider call, also per file segment. Actual provider tokens are taken into account where available. usage.cost and usage.cost_micro_eur show billed costs, not reservations still open.

Use an Idempotency-Key for creation and, on an unclear response, repeat the same request with the same key. Ticket renewal gets a new idempotency key. Credit, key blocks and team limits also apply during processing. Unclear provider errors can leave a reservation open until the usage has been settled.

Finished results stay retrievable for 24 hours after completion. expires_at describes this retention period, ticket_expires_at only the ticket validity. Uploads and working files are deleted after completion, cancellation or an error. You delete completed live sessions with DELETE /audio/transcription-sessions/{id}.

Typical errors: HTTP 422 for unsuitable options, limits or sources; HTTP 429 for too many parallel sessions; HTTP 503 with audio_disabled, audio_model_unavailable or audio_pricing_unavailable when the feature, the model or the price is unavailable. A WebSocket upgrade with an invalid, expired or already used ticket is rejected. For accepted jobs and sessions, also check status and error; a successful status call does not yet mean a successful transcription.

Availability of live transcription

Live transcription is enabled separately and is only available for models that GET /models lists with the value live in transcription.modes. The table above shows which mode a model can generally handle; your current model list is what counts for your integration.

POST
/v1/audio/transcriptions

Transcribe a file

Transcribe a file. A FlowModels key is required. Finished results stay available for 24 hours after completion.

Request body

model string
required
Released identifier provider/model-id from GET /models
language string
Model-dependent language code, for example de
timestamps boolean
Explicitly enable timestamps; default false
diarize boolean
Speaker attribution; no model currently offers it, so true is rejected with HTTP 422. Default false
file file
required
Audio file, at most 200 MiB and eight hours; observe the model limits
background boolean
Required above 24 MiB or ten minutes. Response 202 with a job ID.
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}

Retrieve a job

Retrieve a job. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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

Cancel a job

Cancel a job. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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}

Delete a completed job

Delete a completed job. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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

Create a live session

Create a live session. A FlowModels key is required. Finished results stay available for 24 hours after completion.

Request body

model string
required
Released identifier provider/model-id from GET /models
language string
Model-dependent language code, for example de
timestamps boolean
Explicitly enable timestamps; default false
diarize boolean
Speaker attribution; no model currently offers it, so true is rejected with HTTP 422. Default false
source string
required
push for apps or url for direct HTTP(S) audio streams
url string
Required with source=url. No private targets, credentials or HLS playlists.
max_seconds integer
Default 7200, at most 28800 seconds
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}

Retrieve a session and confirmed segments

Retrieve a session and confirmed segments. A FlowModels key is required. Finished results stay available for 24 hours after completion.

Query parameters

after_sequence integer
Retrieve only later confirmed segments, at most 1000 per page
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

Request a new connection ticket

Request a new connection ticket. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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

End the recording and finish the results

End the recording and finish the results. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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}

Delete a completed session

Delete a completed session. A FlowModels key is required. Finished results stay available for 24 hours after completion.

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

Generate videos

Models and parameters

Videos are generated in the background. You start a job, immediately get 202 with a job ID, and then poll the status or let a webhook notify you. There is no automatic model switch.

ModelInputDuration (seconds)ResolutionAspect ratioFurther fields
bytedance/seedance-2.5/text-to-videoPrompt4 to 30480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9generate_audio, output_format
bytedance/seedance-2.5/image-to-videoImage, optionally prompt and end image4 to 30480p, 720p, 1080pFollows the imagegenerate_audio
minimax/h3/text-to-videoPrompt5 to 152Kauto, adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16aigc_watermark
minimax/h3/image-to-videoImage and prompt, optionally end image5 to 152KAs for text-to-videoaigc_watermark
alibaba/wan-3.0/text-to-videoPrompt2 to 30480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, adaptivegenerate_audio, enable_thinking, seed
alibaba/wan-3.0/image-to-videoImage and prompt, optionally end image2 to 30480p, 720p, 1080pAs for text-to-videogenerate_audio, enable_thinking, seed

Only use models from your current response to GET /models; a model that has not been released yet is rejected. Fields a model does not know and unknown fields are rejected with 422 and param before any reservation. For example, Seedance image-to-video accepts neither aspect_ratio nor output_format, and models without an audio track reject generate_audio.

Pass images

Image-to-video models need a start image, either as image_url (a public https address or a data: URL) or as image_file_id of a file of this team from POST /files. JPEG, PNG, WebP and GIF up to 10 MiB are allowed. The same rules apply to the end image with end_image_url or end_image_file_id. A foreign or unknown file is rejected with 422 video_input_invalid.

Flow and status

  1. POST /videos checks the parameters, reserves the full price of the requested seconds and answers with 202.
  2. status is first queued, then in_progress, and finally completed, failed or cancelled. Poll at intervals of at least five seconds or use webhooks.
  3. Once the video is finished, the response contains content_url, content_type and size_bytes. GET /videos/{id}/content answers with 302 to a download URL that is valid for 15 minutes.
  4. The video stays retrievable for seven days after completion; after that, the file and the job are deleted automatically. expires_at names the exact time. DELETE /videos/{id} deletes a finished job earlier.

POST /videos/{id}/cancel cancels a job as long as it is not running yet and releases the reservation. If generation has already started, the API answers with 409 video_not_cancellable; the job then runs to the end and is billed. If the API answers with 202, the cancellation is still being carried out; check the result with GET /videos/{id}.

Costs and reservation

Billing is per second of the finished video, at the price of the chosen combination of model, resolution, audio and, where applicable, enable_thinking. pricing.variants in GET /models states the price in euros per second for each variant. The price is fixed when the job starts and reserved until completion. Only a video that was stored successfully with us is charged; failed, rejected and cancelled jobs cost nothing. If a combination has no price, the API answers with 503 video_pricing_unavailable and starts nothing.

Limits and error codes

The number of concurrently active videos depends on your rate-limit tier: 3, 5, 10 or 20 per team. If the limit is exceeded, the API answers with 429 video_concurrency_exceeded and Retry-After. With the Idempotency-Key header you can safely repeat a request after a network error; no second video is created.

  • 422 invalid_video_request: A field does not fit the model, see param.
  • 422 video_input_invalid: The image is missing, invalid or too large.
  • 429 insufficient_quota, 429 spend_limit_exceeded: Credit or spending limit is not sufficient.
  • 429 video_concurrency_exceeded: Too many active videos.
  • 503 video_model_unavailable, 503 video_pricing_unavailable, 503 video_provider_unavailable: Try again later; your credit has not been charged.
  • 503 video_storage_unavailable: The video could not be deleted right now; the job is kept. Try again later, see Retry-After.
  • 404 video_not_found: Unknown or foreign job ID.
  • 409 video_not_cancellable, 409 video_not_deletable, 409 video_not_ready: The current status does not allow the action.

A job with status failed contains error.code, for example video_generation_failed or video_content_rejected. Webhooks deliver the events video.completed, video.failed and video.cancelled; the delivery never contains the prompt.

POST
/v1/videos

Create a video

Create a video. A FlowModels key is required.

Request body

model string
required
Released identifier from GET /models, for example bytedance/seedance-2.5/text-to-video
prompt string
Required for all text-to-video models and for MiniMax and Wan image-to-video, optional for Seedance image-to-video. At most 7,000 characters.
image_url string
Required for image-to-video unless image_file_id is set: https URL or data:image/...;base64 URL. JPEG, PNG, WebP or GIF, at most 10 MiB.
image_file_id string
file_id of an image file this team uploaded earlier, instead of image_url
end_image_url string
End image, image-to-video models only. Same formats as image_url.
end_image_file_id string
file_id of the end image, instead of end_image_url
duration integer
Duration in seconds, range per model, see table. Default 5.
resolution string
Resolution per model, see table
aspect_ratio string
Aspect ratio per model. Seedance image-to-video rejects this field.
generate_audio boolean
Generate audio. Seedance and Wan only, default true.
output_format string
mp4 or mov. Seedance text-to-video only.
enable_thinking boolean
Wan only, default false. Has its own price per second.
seed integer
Wan only, 0 to 2147483647
aigc_watermark boolean
MiniMax only, default 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":"A paper boat on a calm lake at sunrise","duration":5,"resolution":"720p"}'

# Poll the status until status is "completed", "failed" or "cancelled"
curl --fail-with-body "https://api.flowmodels.one/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY"

# Download the finished video (302 to a short-lived download URL)
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

List videos

List videos. A FlowModels key is required.

Query parameters

limit integer
Entries per page, default 20, at most 100
after string
last_id of the previous page
status string
queued, in_progress, completed, failed or cancelled
curl -X GET "https://api.flowmodels.one/v1/videos" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/videos/{id}

Retrieve a video

Retrieve a video. A FlowModels key is required.

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

Download the finished video

Download the finished video. A FlowModels key is required.

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

Cancel a video

Cancel a video. A FlowModels key is required.

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}

Delete a video

Delete a video. A FlowModels key is required.

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

Generate images

Models and parameters

An image is created within the request: you send a prompt and get the finished image in the same response, usually after a few seconds. There is no automatic model switch.

ModelSizesQualityEditing
openai/gpt-image-2.6-sunburstsquare, portrait, landscape, 2klow, mediumYes
google/gemini-3.1-flash-imagesquare, portrait, landscape, 2kmediumNo
google/gemini-nano-banana-2.1square, portrait, landscape, 2kmediumNo
minimax/h3-imagesquare, portrait, landscape, 2kmediumYes
minimax/h3-image-highspeedsquare, portrait, landscape, 2kmediumYes
ionos/black-forest-labs/FLUX.2-klein-4Bsquare, portrait, landscape, 2kmediumYes

ionos/black-forest-labs/FLUX.2-klein-4B runs on the IONOS AI Model Hub in Berlin (GDPR, EU-hosted). According to IONOS the model only takes the first 256 tokens of the prompt into account; a longer prompt is accepted, but its remainder is not rendered.

The former ID google/gemini-3.1-flash-image-preview is still accepted. Google has shut that preview model down, so the request is generated with google/gemini-3.1-flash-image and billed at its price; model in the response names that model.

square is square, portrait upright, landscape wide and 2k a wide landscape format in higher resolution. Only use models from your current response to GET /models; there, image lists the sizes, the qualities and whether the model can edit. Fields a model does not know and unknown fields are rejected with 422 and param before any reservation.

Edit images

POST /images/edits additionally takes an image, either as image_url (a public https address or a data: URL) or as image_file_id of a file of this team from POST /files. JPEG, PNG and WebP up to 10 MiB are allowed. A foreign or unknown file is rejected with 422 image_input_invalid. For ionos/black-forest-labs/FLUX.2-klein-4B the image must be at least 64 pixels on each side and no more extreme than 8:1, otherwise it is rejected with 422 image_input_invalid as well. The result always has the chosen size.

Response and retrieval

The response follows the structure of the OpenAI images API: created and data with exactly one entry. With response_format url it holds a download address, with b64_json the image itself as Base64. In addition there are id, content_type, size_bytes, expires_at and usage. GET /images/{id}/content answers with 302 to a download URL that is valid for 15 minutes. The image stays retrievable for seven days and is then deleted automatically. DELETE /images/{id} deletes it earlier.

Costs and reservation

Billing is per image, at the price of the chosen combination of model, size and quality. pricing.variants in GET /models states the price in euros per image for each variant. The amount is reserved before generation and only charged once the image has been stored with us. Rejected and failed requests cost nothing. If a model has no price, the API answers with 503 image_pricing_unavailable and generates nothing.

Limits and error codes

A generation takes one of the concurrent request slots of your rate-limit tier. With the Idempotency-Key header you can safely repeat a request after a network error; no second image is created. There are no webhooks for images, because the response contains the finished image.

  • 422 invalid_image_request: A field does not fit the model, see param.
  • 422 image_input_invalid: The image to edit is missing, invalid or too large.
  • 422 image_request_rejected: The model rejected the request.
  • 422 image_content_rejected: The image was rejected because of its content.
  • 429 insufficient_quota, 429 spend_limit_exceeded: Credit or spending limit is not sufficient.
  • 503 image_model_unavailable, 503 image_pricing_unavailable, 503 image_provider_unavailable: Try again later; your credit has not been charged.
  • 404 image_not_found: Unknown, expired or foreign image ID.
  • 409 image_not_ready, 409 image_not_deletable: The current status does not allow the action.
POST
/v1/images/generations

Generate an image

Generate an image. A FlowModels key is required.

Request body

model string
required
Released identifier from GET /models, for example openai/gpt-image-2.6-sunburst
prompt string
required
Description of the image, at most 4,000 characters
size string
square, portrait, landscape or 2k. Default square.
quality string
low or medium for openai/gpt-image-2.6-sunburst (default low), only medium for google/gemini-3.1-flash-image, google/gemini-nano-banana-2.1, minimax/h3-image, minimax/h3-image-highspeed and ionos/black-forest-labs/FLUX.2-klein-4B
n integer
Number of images, only 1 is allowed
response_format string
url (default) or 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": "A paper boat on a calm lake at sunrise", "size": "landscape", "quality": "low"}'
POST
/v1/images/edits

Edit an image

Edit an image. A FlowModels key is required.

Request body

model string
required
Released identifier from GET /models, for example openai/gpt-image-2.6-sunburst
prompt string
required
Description of the image, at most 4,000 characters
size string
square, portrait, landscape or 2k. Default square.
quality string
low or medium for openai/gpt-image-2.6-sunburst (default low), only medium for google/gemini-3.1-flash-image, google/gemini-nano-banana-2.1, minimax/h3-image, minimax/h3-image-highspeed and ionos/black-forest-labs/FLUX.2-klein-4B
n integer
Number of images, only 1 is allowed
response_format string
url (default) or b64_json
image_url string
Image to edit, unless image_file_id is set: https URL or data:image/...;base64 URL. JPEG, PNG or WebP, at most 10 MiB.
image_file_id string
file_id of an image file this team uploaded earlier, instead of 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}

Retrieve an image

Retrieve an image. A FlowModels key is required.

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

Download the image

Download the image. A FlowModels key is required.

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}

Delete an image

Delete an image. A FlowModels key is required.

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

Decisions

Typed questions instead of free text

POST /decisions answers named questions about shared content with probabilities instead of prose. The format follows the OpenAI Decisions API, so you can carry over an existing integration. There are four question types:

  • predicate: yes or no. Answer probability from 0 to 1.
  • choice: one of several options from choices. Answer choice, probabilities per option and confidence.
  • score: a rating on the levels in levels, from low to high. Answer score (probability-weighted mean of the levels, starting at 0), probabilities per level and confidence.
  • box: TypeSafe Jev only. Locates what is described in an image from input. Answer box with top, bottom, left and right as fractions of image height and width (0 to 1) and confidence (may be null).

The answers in answers follow the order of your questions and each carries the question's name. If a model refuses a single question, that entry has type: refusal.

Models and capabilities

ModelQuestion typesQuestions per requestImagesText limit
openai/decisions/gpt-6-lunapredicate, choice, score400YesChecked by the provider
typesafe/jev-1.14.0predicate, choice, score, box100Yes, PNG and JPEG256,000 characters of input, 128,000 per question
typesafe/jev-latestas jev-1.14.0100Yes, PNG and JPEGas jev-1.14.0

typesafe/jev-latest always points to the current Jev model. openai/decisions/gpt-6-luna is gpt-6-luna through the OpenAI Decisions API; the chat model of the same name, openai/gpt-6-luna, is not affected and cannot be used here. GET /models lists the three decision models as kind: decision with their capabilities under decision. Up to eight images per request are allowed, in input and in a question's instructions together. prompt_cache_key is OpenAI only.

Checks before any reservation

A malformed body is rejected with 400 invalid_field_value, a field the chosen model cannot handle (for example box on OpenAI or too many questions) with 422 unsupported_for_model. In both cases param names the full field path, for example questions.3.type. Unknown fields are rejected, not ignored.

Costs

Only input tokens are billed; output is free. With OpenAI, usage.input_tokens already includes the cache reads and cache writes from input_tokens_details; cache reads cost less. pricing in GET /models states the prices in euros per 1M tokens (input, cached_input, cache_write). An upper bound is reserved before the call and the actual usage is charged. If the model returns no usable answer, the request costs nothing.

usage.cost (euros as a decimal string) and usage.cost_micro_eur state the amount charged, usage.cost_status its state: settled when the amount is booked, pending when the booking is completed later. While it is pending, cost and cost_micro_eur are null; the final amount is then included in GET /usage.

Error codes

  • 400 invalid_field_value: The body is malformed, see param.
  • 404 model_not_found: The ID is not a decision model.
  • 413 payload_too_large, 415 invalid_content_type: Body too large or not JSON.
  • 422 unsupported_for_model: A field does not fit the model, see param.
  • 422 decision_input_invalid: An image is invalid, unreachable or in the wrong format.
  • 422 decision_request_rejected: The model rejected the request; nothing was charged.
  • 429 insufficient_quota, 429 spend_limit_exceeded: Credit or spending limit is not sufficient.
  • 429 decision_provider_rate_limited: The provider is busy, wait the seconds from Retry-After.
  • 502 decision_provider_invalid_response, 503 decision_provider_unavailable, 503 decision_model_unavailable, 503 decision_pricing_unavailable: Try again later; your credit has not been charged.
POST
/v1/decisions

Ask for decisions

Answer typed questions about shared content. A FlowModels key is required.

Request body

model string
required
openai/decisions/gpt-6-luna, typesafe/jev-1.14.0 or typesafe/jev-latest (see GET /models, kind decision)
input string|array
required
Shared content for all questions: a string or a list of messages with role (user, developer, system) and content. user messages allow the parts input_text, input_image (image_url as https or data URL) and input_json (data); developer and system messages allow input_text only.
questions array
required
1 to 400 questions (fewer depending on the model), each with type (predicate, choice, score, box), a unique name and instructions (string or list of input_text and input_image). choice needs choices [{value, description}] with 2 to 255 unique entries, score needs levels [{label, description}] with 2 to 10 levels from low to high. description is optional in both; a short description is recommended.
prompt_cache_key string
openai/decisions/gpt-6-luna only: key that partitions prompt cache reuse
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

Manage the history yourself or use Brain
Without external_identifier, context management stays with the client. With an identifier, Brain adds the stored history, memories and relevant file passages. Both variants support streaming.

Start a conversation

The following example runs a call without any stored end-user context. Replace the token and pick a model from your current model list. For Brain, also send external_identifier as a JSON string. The full model identifier and the FlowModels key stay the same in both variants.

Let the model call your own functions

You can offer the model your own functions. FlowModels does not execute these functions. The model decides which function should be called with which arguments, you run the call in your own system and send the result back in the next turn. The flow therefore always consists of two billed requests.

First turn. You send tools and optionally tool_choice:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "What is the weather like in Berlin?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city.",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }]
}

The response carries finish_reason: "tool_calls", content: null and the calls the model wants. arguments is a string containing JSON, not an object:

{
  "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"
  }]
}

Second turn without Brain. You send the previous history, the model's message and your result as a message with role: "tool". The tool_call_id must match the id from the call, otherwise the API answers with HTTP 400:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "user", "content": "What is the weather like in Berlin?"},
    {"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 degrees, cloudy"}
  ],
  "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}]
}

When streaming, the calls arrive in their own chunk immediately before the final chunk: choices[0].delta.tool_calls contains the complete entry including index, and the final chunk carries finish_reason: "tool_calls". On the Responses endpoint the calls instead appear as entries of type function_call in output, and you reply in the next turn with an entry of type function_call_output.

Second turn with Brain. Send the same external_identifier, the returned conversation UUID and only the tool result. The stored assistant call stays on the server and tool_call_id is checked against that stored call. Sending the entire old history again creates duplicate context.

flowai_tools controls something else, namely the server-side tools of FlowModels. Sending both fields in one request is rejected with HTTP 400 and invalid_field_value.

Structured output: what providers accept

json_object and json_schema in capabilities tell you what a model supports natively; if the capability is missing, the API answers with 400 unsupported_for_model. Anthropic models report neither, Perplexity models only json_schema. With Gemini models, keys outside the supported schema subset are filtered out. If a provider still rejects a requested schema, for example strict: true with an invalid schema, the API answers with 400 invalid_field_value and param: response_format; the provider's error text is not passed on.

POST
/v1/chat/completions

Chat Completions

Sends messages to a released provider model. Without an end-user identifier, the client manages the history; with one, Brain adds the personal context.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
messages array
required
New messages with role and content; at least one non-empty user message
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
max_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
stream boolean
true returns Chat Completions chunks as SSE; default false
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning_effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max. Without a value the provider default applies, so no reasoning budget you did not ask for is incurred. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models; an unsupported level is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The json_object and json_schema fields in GET /models state what the model supports natively; without the capability the API answers HTTP 400 and unsupported_for_model instead of silently returning plain text. With json_object, FlowModels adds a short JSON hint if the word json appears in no message, because some providers reject JSON mode otherwise. With json_schema, strict: false applies unless you send strict. If the provider still rejects the schema, the API answers HTTP 400, invalid_field_value and param response_format
tools array
Your own functions in the format [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON Schema>}}]. At most 128 entries, each description at most 65,536 characters, each schema at most 65,536 bytes as JSON. FlowModels does not execute these functions: the model answers with tool_calls, you run the function in your own system and send the result back as a message with role "tool". Whether a model accepts functions is listed in tools from GET /models; without the capability the API answers HTTP 400 and unsupported_for_model. Combining it with flowai_tools is not allowed and is rejected with HTTP 400 and invalid_field_value
tool_choice string|object
Controls tool selection: "auto", "none", "required" or {"type":"function","function":{"name":…}} for exactly one function. Only allowed together with tools, and the named function must exist in tools. Without a value the provider default applies
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
max_completion_tokens integer
The same setting as max_tokens under the name used by the Responses API. Sending both with different values is rejected
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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":"Summarize the benefits of clear project planning."}], "max_tokens": 512, "stream": false}'
POST
/v1/chat/completions
SSE / streaming

Chat Completions as SSE

Sends messages to a released provider model. Without an end-user identifier, the client manages the history; with one, Brain adds the personal context.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
messages array
required
New messages with role and content; at least one non-empty user message
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
max_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
stream boolean
true returns Chat Completions chunks as SSE; default false
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning_effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max. Without a value the provider default applies, so no reasoning budget you did not ask for is incurred. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models; an unsupported level is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The json_object and json_schema fields in GET /models state what the model supports natively; without the capability the API answers HTTP 400 and unsupported_for_model instead of silently returning plain text. With json_object, FlowModels adds a short JSON hint if the word json appears in no message, because some providers reject JSON mode otherwise. With json_schema, strict: false applies unless you send strict. If the provider still rejects the schema, the API answers HTTP 400, invalid_field_value and param response_format
tools array
Your own functions in the format [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON Schema>}}]. At most 128 entries, each description at most 65,536 characters, each schema at most 65,536 bytes as JSON. FlowModels does not execute these functions: the model answers with tool_calls, you run the function in your own system and send the result back as a message with role "tool". Whether a model accepts functions is listed in tools from GET /models; without the capability the API answers HTTP 400 and unsupported_for_model. Combining it with flowai_tools is not allowed and is rejected with HTTP 400 and invalid_field_value
tool_choice string|object
Controls tool selection: "auto", "none", "required" or {"type":"function","function":{"name":…}} for exactly one function. Only allowed together with tools, and the named function must exist in tools. Without a value the provider default applies
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
max_completion_tokens integer
The same setting as max_tokens under the name used by the Responses API. Sending both with different values is rejected
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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":"Summarize the benefits of clear project planning."}], "max_tokens": 512, "stream": true}'

Responses

Choose a response mode

Plain text goes into input; structured messages are possible as well. Read the text from output[].content[] with type: output_text. Without any further option you get JSON synchronously. stream: true returns SSE events. background: true starts a background job and answers with HTTP 202 without streaming. The two options can be combined.

Response retention

With store: true, the response and its events stay retrievable for 24 hours after completion. Storage is enabled by default in the background, otherwise disabled. background: true must not be combined with store: false. A response that was not stored cannot be retrieved with GET after completion. Response retention is separate from the permanent Brain conversation history.

Polling and SSE resumption

Retrieve stored responses at GET /responses/{response_uuid}. For events, use ?stream=true. Store the last sequence_number from an event; with starting_after=N you only get later events. Such a retrieval does not start a new model call. The cursor is a non-negative integer and needs stream=true. Expired, unstored and foreign responses return 404 response_not_found.

An interrupted observation stream does not end a background job. You can observe it again or cancel it via POST /responses/{response_uuid}/cancel. Costs already incurred remain. For results via webhook, register a target and send its UUID as webhook_endpoint_id.

POST
/v1/responses

Responses

Alternative with input instead of messages, synchronous, as SSE or in the background. An end-user identifier optionally adds Brain context.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
input string|array
required
New user message as text or a supported message structure
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
stream boolean
Receive response events as SSE; can also be combined with background
background boolean
Run in the background; without stream, HTTP 202 with a response ID follows
store boolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_id uuid
Registered webhook target for a background job
max_output_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning.effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max, on this endpoint inside the reasoning object instead of reasoning_effort. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models. Without a value the provider default applies; a level the model does not know is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape as for Chat Completions: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The response mirrors it back as text.format with the schema embedded flat; without a value the response has no text field
text.format object
Alternative spelling of the OpenAI Responses API, as the official SDKs send it: {"type":"json_object"} or {"type":"json_schema","name":…,"schema":…,"strict":…} with a flat schema. It works exactly like response_format. Sending both fields is rejected with HTTP 400, as are further keys in text such as verbosity
tools array
Your own functions, in the same spelling as for Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. The response mirrors them back in the Responses spelling with a flat name, but you always send the nested form. FlowModels does not execute the functions
tool_choice string|object
As for Chat Completions: "auto", "none", "required" or an object naming exactly one function. Both spellings are accepted, {"type":"function","name":…} as well as {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
metadata object
Up to 16 string pairs that are kept with the stored response and returned in it. On Chat Completions the field is rejected because nothing is stored there
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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": "Summarize the benefits of clear project planning.", "max_output_tokens": 512}'
POST
/v1/responses
SSE / streaming

Responses as SSE

Alternative with input instead of messages, synchronous, as SSE or in the background. An end-user identifier optionally adds Brain context.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
input string|array
required
New user message as text or a supported message structure
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
stream boolean
Receive response events as SSE; can also be combined with background
background boolean
Run in the background; without stream, HTTP 202 with a response ID follows
store boolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_id uuid
Registered webhook target for a background job
max_output_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning.effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max, on this endpoint inside the reasoning object instead of reasoning_effort. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models. Without a value the provider default applies; a level the model does not know is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape as for Chat Completions: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The response mirrors it back as text.format with the schema embedded flat; without a value the response has no text field
text.format object
Alternative spelling of the OpenAI Responses API, as the official SDKs send it: {"type":"json_object"} or {"type":"json_schema","name":…,"schema":…,"strict":…} with a flat schema. It works exactly like response_format. Sending both fields is rejected with HTTP 400, as are further keys in text such as verbosity
tools array
Your own functions, in the same spelling as for Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. The response mirrors them back in the Responses spelling with a flat name, but you always send the nested form. FlowModels does not execute the functions
tool_choice string|object
As for Chat Completions: "auto", "none", "required" or an object naming exactly one function. Both spellings are accepted, {"type":"function","name":…} as well as {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
metadata object
Up to 16 string pairs that are kept with the stored response and returned in it. On Chat Completions the field is rejected because nothing is stored there
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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":"Summarize the benefits of clear project planning.","max_output_tokens":512,"stream":true,"store":true}'
POST
/v1/responses

Responses in the background

Starts a stored background job and answers with HTTP 202. Use the response ID for polling, SSE and cancellation.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
input string|array
required
New user message as text or a supported message structure
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
stream boolean
Receive response events as SSE; can also be combined with background
background boolean
Run in the background; without stream, HTTP 202 with a response ID follows
store boolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_id uuid
Registered webhook target for a background job
max_output_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning.effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max, on this endpoint inside the reasoning object instead of reasoning_effort. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models. Without a value the provider default applies; a level the model does not know is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape as for Chat Completions: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The response mirrors it back as text.format with the schema embedded flat; without a value the response has no text field
text.format object
Alternative spelling of the OpenAI Responses API, as the official SDKs send it: {"type":"json_object"} or {"type":"json_schema","name":…,"schema":…,"strict":…} with a flat schema. It works exactly like response_format. Sending both fields is rejected with HTTP 400, as are further keys in text such as verbosity
tools array
Your own functions, in the same spelling as for Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. The response mirrors them back in the Responses spelling with a flat name, but you always send the nested form. FlowModels does not execute the functions
tool_choice string|object
As for Chat Completions: "auto", "none", "required" or an object naming exactly one function. Both spellings are accepted, {"type":"function","name":…} as well as {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
metadata object
Up to 16 string pairs that are kept with the stored response and returned in it. On Chat Completions the field is rejected because nothing is stored there
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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": "Summarize the benefits of clear project planning.", "max_output_tokens": 512, "background": true, "store": true}'
POST
/v1/responses
SSE / streaming

Watch a background job directly as SSE

Combines background and stream. The worker keeps running if the observation stream is interrupted.

Request body

model string
required
Full identifier from GET /models in the format provider/model-id
external_identifier string
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
input string|array
required
New user message as text or a supported message structure
conversation uuid
UUID from the previous response of the same end user; omit it for a new conversation
stream boolean
Receive response events as SSE; can also be combined with background
background boolean
Run in the background; without stream, HTTP 202 with a response ID follows
store boolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_id uuid
Registered webhook target for a background job
max_output_tokens integer
Upper limit for the output, 1 to 128,000. Without a value the model's maximum applies; if none is stored for the model, 4,096 tokens apply. null counts as no value. OpenAI models accept at least 16 tokens; a smaller value is rejected with 400
context_compression boolean
Allows FlowModels to summarise an overly long history you sent yourself, server-side; default false. Without it, an overly long history is rejected with 400 context_length_exceeded rather than truncated. The summary is an additional paid model call and is reported in usage.flowai.compression
reasoning.effort string
Reasoning depth of the model: none, minimal, low, medium, high, xhigh or max, on this endpoint inside the reasoning object instead of reasoning_effort. Which levels a model accepts is listed in capabilities.reasoning_levels from GET /models. Without a value the provider default applies; a level the model does not know is rejected with HTTP 400 and unsupported_for_model
web_search boolean
Turns on the provider's native web search. Off by default, because every search is billed additionally. Models without native search reject true; models with built-in search (Perplexity, Groq Compound) reject false, in both cases with HTTP 400 and unsupported_for_model. The web_search and web_search_forced fields in GET /models are authoritative
response_format object
Output shape as for Chat Completions: {"type":"text"}, {"type":"json_object"} or {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. The response mirrors it back as text.format with the schema embedded flat; without a value the response has no text field
text.format object
Alternative spelling of the OpenAI Responses API, as the official SDKs send it: {"type":"json_object"} or {"type":"json_schema","name":…,"schema":…,"strict":…} with a flat schema. It works exactly like response_format. Sending both fields is rejected with HTTP 400, as are further keys in text such as verbosity
tools array
Your own functions, in the same spelling as for Chat Completions: [{"type":"function","function":{"name":…,"parameters":<JSON Schema>}}]. The response mirrors them back in the Responses spelling with a flat name, but you always send the nested form. FlowModels does not execute the functions
tool_choice string|object
As for Chat Completions: "auto", "none", "required" or an object naming exactly one function. Both spellings are accepted, {"type":"function","name":…} as well as {"type":"function","function":{"name":…}}
parallel_tool_calls boolean
Allows or forbids several function calls in one response. Only allowed together with tools. Not every model has this switch; parallel_tool_calls in GET /models is authoritative, otherwise the API answers HTTP 400 and unsupported_for_model
stream_options object
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
user string
Your own identifier of the calling end user for abuse tracing, up to 128 characters. It does not replace external_identifier and does not enable Brain context
metadata object
Up to 16 string pairs that are kept with the stored response and returned in it. On Chat Completions the field is rejected because nothing is stored there
search_domain_filter array
Restricts native web search to up to 20 domains, for example ["company.de"], or excludes them with a leading minus sign, for example ["-reddit.com"]. Either allowed domains only or exclusions only; domains without https:// and without a path, subdomains are included. The field turns on web search and is billed additionally. How many domains a model accepts is listed in GET /models under capabilities.web_search_domain_filter_max (xAI 5, otherwise 20); models without a domain filter such as Gemini reject the field with 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":"Summarize the benefits of clear project planning.","max_output_tokens":512,"stream":true,"store":true,"background":true}'
GET
/v1/responses/{response_uuid}

Retrieve the response status

Returns a stored response of the same team within its retention period.

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

Resume the stored event stream

Returns only events after the stored sequence_number, without starting a new model call.

Query parameters

stream boolean
required
true for SSE
starting_after integer
Last received sequence_number; from 0, exclusive cursor
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

Cancel a response

Idempotently requests cancellation of a background job and returns its current state.

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

Continue conversations

Send the UUID of the previous response

On the next call, send the same external_identifier, the returned conversation UUID and only the new messages. The existing history is added on the server. If you send the entire old history again, you create duplicate context.

{
  "model": "groq/openai/gpt-oss-120b",
  "external_identifier": "customer-42",
  "conversation": "018f1234-5678-7abc-9def-0123456789ab",
  "messages": [{"role": "user", "content": "Give me three concrete next steps for this."}]
}

A request without conversation starts a new conversation. An unknown UUID, or one belonging to another workspace or end user, returns 404 conversation_not_found. Only one call may run at a time for the same conversation; concurrent calls get 409 conversation_in_progress.

History, files and memories

Brain adds the stored conversation history and relevant memories and file passages of the same person. The context is adjusted to the model's token budget. Long histories are summarised step by step; those model calls also count as paid usage. Faulty summaries do not replace a valid stored state. Without an end-user identifier, the client manages the history and no personal Brain context is searched.

End-user management

Deletion with retention obligations
Deletion removes personal working data. Billing and usage rows are kept for retention reasons.

External identifier and public UUID

external_identifier is your own stable string, for example customer-42. With it you assign requests within your workspace to an end user. Numeric identifiers must also be sent as a JSON string. The first inference call without conversation creates an unknown end user automatically.

With POST /end-users you can create or resolve the end user beforehand. The returned id is the public UUID for management and file endpoints. This UUID is different from your external identifier and from the conversation UUID.

History compression

With external_identifier, the history is stored by us. If it grows beyond the model's input window, we summarise the older turns and store that summary. Each turn is therefore compressed exactly once and paid for exactly once. A fixed number of the most recent stored turns always stays verbatim; everything before that reaches the model only through the summary. Nothing is lost: a turn only leaves the verbatim history after the summary has absorbed it.

Without external_identifier, the history is yours and we do not summarise anything on our own. If the history you send does not fit into the input window, we answer with 400 context_length_exceeded; the message names max_input_tokens and estimated_input_tokens. Then send fewer messages, or set context_compression: true and thereby explicitly allow compression. This compression is an additional paid model call per request and is reported in the response block usage.flowai.compression with calls, input_tokens, output_tokens and cost_micro_eur. Without compression, the field is absent.

Metadata and automatic memories

Metadata holds at most 50 entries with keys of up to 64 characters and strings of up to 1,000 characters or null as the value. Automatic memory extraction is enabled by default for new end users as soon as you use Brain with external_identifier. No additional opt-in is required. Without an external identifier, no Brain is used. Disable extraction if needed with PATCH /end-users/{end_user_uuid} and memory_extraction_enabled: false. Settings that were already explicitly disabled are kept.

Delete end-user data

DELETE /end-users/{end_user_uuid} removes this person's personal working data from API use. Private file objects are then deleted in the background; temporary storage errors are retried. deleted: true therefore does not confirm that the physical deletion of all objects has finished. Billing and usage data are kept. Unknown and foreign UUIDs get the same response with 404 end_user_not_found.

Retrieve the deletion receipt

GET /end_users/{end_user_uuid}/erasures lists the deletion runs for this identifier, GET /end_users/{end_user_uuid}/erasures/{run_uuid} returns a single receipt. Both remain available after deletion, because that is exactly when you need the proof. status names the state, requested_at the time of your request and completed_at the completion or null while objects are still being removed in the background.

manifest_summary.resources states, per data type, the count before and after the run. The receipt contains numbers only: no texts, no file names and no identifiers. Data types without a public name are not reported.

GET
/v1/end-users

List end users

Lists the end users of the authenticated workspace with a UUID cursor.

Query parameters

limit integer
Number of entries from 1 to 100, default 100
after uuid
UUID from last_id of the previous page
curl -X GET "https://api.flowmodels.one/v1/end-users" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
POST
/v1/end-users

Create or resolve an end user

Creates an end user from your stable external identifier or returns the existing record.

Request body

external_identifier string
required
Your stable, non-sensitive identifier for this end user
metadata object
Optional metadata of your own
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}

Retrieve an end user

Returns an end user by their 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}

Update an end user

Adds metadata or changes the automatic memory extraction of an end user.

Request body

metadata object
Metadata that is merged with the existing values
memory_extraction_enabled boolean
Enables or disables automatic memory extraction
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}

Delete an end user

Deletes the personal working data of an end user. Billing and usage rows are kept.

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

List deletion runs

Lists the deletion receipts for an end-user identifier, also after deletion.

Query parameters

limit integer
Entries per page, 1 to 100, default 20
after string
Cursor from last_id of the previous page
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}

Retrieve a deletion receipt

Returns a single deletion receipt with timestamps and counts per data type.

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"

Files as end-user context

Assign documents to a person

Create or resolve the end user with POST /end-users. Use their public UUID for POST /end_users/{end_user_uuid}/files. Note the underscore in end_users; end-user management, by contrast, uses end-users.

Send the file as multipart/form-data with purpose=user_data. PDF, DOCX, XLSX, TXT, Markdown and CSV are supported. The default limits are 32 MiB per file, 100 files per end user and 5 GiB per workspace. For multipart requests, your HTTP client generates the content type including the boundary.

Processing happens in the background

A successful upload answers with HTTP 201 and status: pending. Only after extraction and indexing are matching text passages available for later requests of the same end user. The upload does not yet confirm that the file is already retrievable conversation context. Temporary processing errors are retried; unreadable document content can fail permanently.

List, check, remove individually

GET /end_users/{end_user_uuid}/files lists this person's files, newest first, page by page using limit and after. status names the processing state. DELETE /end_users/{end_user_uuid}/files/{file_uuid} removes a single file including the text passages derived from it; deleting the entire person is no longer required for this. The file ID of this upload still does not belong to the general /files management.

After deletion, a contentless entry without a file name or object remains, so the storage already used stays billable. It appears in no list. Unknown files, files of another person and files of another workspace get the same response with 404 file_not_found.

POST
/v1/end_users/{end_user_uuid}/files

Upload an end-user file

Stores a text file for the end user and starts its processing. Use multipart/form-data.

Request body

file file
required
Supported text or document file with a file name of up to 255 characters
purpose string
required
Required value user_data; other purposes are rejected
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

List files

Lists the files of an end user, newest first.

Query parameters

limit integer
Entries per page, 1 to 100, default 20
after string
Cursor from last_id of the previous page
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}

Retrieve a file

Returns the details of a single file, without its content.

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}

Delete a file

Removes a single file including the text passages derived from it.

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"

Workspace files

Upload files

Send uploads as multipart/form-data. Permitted purposes are user_data and vision. There is no automatic retention period; files you no longer need must be deleted explicitly.

Metadata and content

The single retrieval returns metadata only. The stored bytes are available solely through the separate content endpoint.

POST
/v1/files

Upload a file

Stores a file for later requests. Use multipart/form-data.

Request body

file file
required
File to upload
purpose string
required
user_data or 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

List files

Lists the files of the workspace with a stable cursor.

Query parameters

purpose string
Filter: user_data or vision
order string
Sort order: asc or desc
limit integer
Number from 1 to 100
after string
Public file ID from 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}

Retrieve file metadata

Returns metadata, not the file content.

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

Download file content

Returns the stored bytes as a download with the original media type.

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}

Delete a file

Deletes the stored bytes and their metadata.

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

Memories

Memories per end user

These endpoints belong to the Brain feature of FlowModels and need a FlowModels key.

All calls bind a memory to exactly one end user via external_identifier. Changes use revision for optimistic conflict detection.

List or search

GET /memories answers two questions over the same entries. Without query you get this person's memories in descending chronological order, page by page via limit and after; this path calls no model and costs nothing. With query, the similarity search runs, which embeds the search text and therefore counts as paid usage.

A search result is a ranking, not a page: the search therefore returns has_more: false and last_id: null and offers no cursor. An after value that does not come from a previous page is rejected with 400 invalid_cursor and never answered with an empty page.

Context for later answers

Stored memories are used as relevant context within the same workspace and end user. Creating a memory manually does not need automatic extraction to be enabled. Keep the returned revision and send it when changing the memory. On 409 memory_revision_conflict, you must fetch the current state again and reconcile the change.

POST
/v1/memories

Create a memory

Stores a personal memory for an end user.

Request body

external_identifier string
required
Your stable external end-user identifier
text string
required
Non-empty text of at most 10,000 characters
kind string
Optional type of the memory
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": "Prefers short summaries.", "kind": "preference"}'
PATCH
/v1/memories/{memory_uuid}

Update a memory

Changes a memory if the given revision is current.

Request body

external_identifier string
required
Your stable external end-user identifier
text string
required
New memory text
revision integer
required
Current revision, at least 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": "Prefers short summaries with three bullet points.", "revision": 1}'
DELETE
/v1/memories/{memory_uuid}

Delete a memory

Deletes a memory of the specified end user.

Request body

external_identifier string
required
Your stable external end-user identifier
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 visible only once
The signing secret is returned only when the target is created. Store it securely and do not publish it.

Targets and signatures

Webhook targets must be publicly reachable HTTPS addresses. The API checks addresses when they are saved and again before every delivery. Register at least one supported event type.

Check deliveries

The delivery history shows status, attempts and the type of error. Permitted status filters are pending, delivered, failed and exhausted.

Supported event types

Besides the four completion events of a background job (response.completed, response.failed, response.cancelled, response.incomplete), you can subscribe to four further types: credit.threshold when reaching one of your warning thresholds in euros (data.metric is balance_floor if the available amount has fallen below the threshold, or spend_month if monthly spending has reached it; data.threshold_eur states the threshold as a decimal string, for example "50.00"), credit.topup_failed for a failed top-up, webhook_endpoint.deactivated when a target has been switched off after repeated failed attempts, and webhook.test for the test delivery you trigger yourself. Video generations add video.completed, video.failed and video.cancelled. Every delivery has the same structure: id, type, created_at and data. webhook_endpoint.deactivated deliberately goes to all other active targets of the workspace, never to the one just switched off: it has just proven it cannot receive anything.

Rotate the secret without a delivery gap

When rotating, the previous secret stays valid until the time in secondary_secret_expires_at. During this window, the webhook-signature header contains two space-separated values of the form v1,<signature>, one per secret. Check all values and accept the delivery on the first match. After the window ends, only the new secret signs. Rotating the secret needs a management key; an inference key gets 403 insufficient_key_scope.

Verify the signature

Every delivery carries the headers webhook-id, webhook-timestamp and webhook-signature. The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{Body}, Base64-encoded with the prefix v1,. The secret is a random 48-character string without a prefix. Use it exactly as you received it: as text, not Base64-decoded. Standard Webhooks libraries decode whsec_ secrets before verifying and therefore compute a different result. So compute the HMAC yourself over the unmodified body and compare in constant time.

POST
/v1/webhook_endpoints

Create a webhook

Registers an HTTPS target and returns the signing secret once.

Request body

url string
required
Publicly reachable HTTPS address, at most 2,048 characters
events array
required
At least one supported event type
description string
Optional description, at most 255 characters
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

List webhooks

Lists the webhook targets of the workspace without secrets.

Query parameters

limit integer
Number from 1 to 100
after uuid
UUID from 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}

Retrieve a webhook

Returns a webhook target without its signing secret.

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}

Update a webhook

Changes the target, events, description or activation status.

Request body

url string
New publicly reachable HTTPS address
events array
New list of supported event types
description string
New description or null
is_active boolean
Deactivates or reactivates the target
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}

Delete a webhook

Deletes the target and its delivery history.

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

List deliveries

Lists delivery attempts with status and error details.

Query parameters

status string
pending, delivered, failed or exhausted
limit integer
Number from 1 to 100
after uuid
UUID from 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

Send a test delivery

Queues a synthetic delivery of type webhook.test. The result appears in the delivery history.

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

Rotate the secret

Generates a new signing secret and returns it once. The previous secret stays valid until the stated time.

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

Billing and API keys

Your own credit in euros

FlowModels does not need a subscription. New teams start with €0 in prepaid mode. Top up at least €20 in the FlowModels dashboard. The top-up amount is the final amount, without additional tax surcharges. Account values are returned as whole micro-EUR: one million micro-EUR are one euro.

Funds are reserved before paid processing. Afterwards, the actual usage including conversation context, retrieval and required summaries is billed. Use usage.cost and usage.currency for the end-customer amount in euros. Missing prices must not be read as free usage.

If history was compressed for a request, usage.flowai.compression lists this portion separately: calls the number of summary calls, input_tokens and output_tokens their tokens and cost_micro_eur their cost in whole micro-EUR. This amount is already included in usage.cost; it is listed separately so that an unexpectedly high amount can be explained from the response itself. Without compression, the field is entirely absent.

There is currently no additional monthly storage fee for stored Brain files. Paid model processing, such as embeddings and image analysis while processing a file, is billed as model usage. File size and team limits still apply.

Postpaid only after activation

Only the administration can activate postpaid. On the first activation, a €50 credit line is preset; the administration can change this amount per team. Credit is used first. The monthly invoice contains only the usage not yet covered by credit. Open amounts and running reservations reduce the usable credit line.

Automatic top-up

Automatic top-up is off by default. Enable it explicitly in the dashboard and choose a verified card belonging to the team. The credit threshold is at least €5, the top-up amount at least €20. You can withdraw your consent at any time. A top-up does not change a monthly key limit.

Separate keys and usage data

Under FlowModels → API keys, create a key with the “Use AI” or “Manage keys” permission. These keys are permanently assigned to FlowModels and to one billing team. Existing FlowSuite keys are not converted. A key with “Manage keys” can only manage keys of the same product via /api/user/api-keys on creativeskyline.de, not below the base URL; without an explicit kind, a key with “Manage keys” is created there too. Model calls need kind: inference.

GET /credits returns the EUR account; available_micro_eur is available credit, spendable_micro_eur also takes the enabled credit line into account. reserved_oldest_at names the time of the oldest reservation still open or null; a very old reservation points to a clarification case the administration resolves. GET /key shows the key used and its limits. The usage overview shows your FlowModels spending. Invoices are under Invoices.

Analyse usage

GET /usage summarises the usage of a period. start and end are day values in the format YYYY-MM-DD; without them, the last 30 days are analysed. group_by accepts day (default), model, api_key and end_user. requests counts requests, not provider calls: a request with a summary and retrieval remains one request. cost_micro_eur is the end-customer amount already billed, in micro-EUR.

GET /usage/requests lists the individual requests, newest first, page by page via limit and after, filterable by status, api_key, end_user and model. The list contains the time, model, provider, status, error code, runtime, token counts and cost. Request and response text are never part of this information; support handles that. Both endpoints can be called with a key with “Manage keys”.

provider names the provider with whom the request was actually billed, in the same spelling as the first half of the model identifier. Keys of a FlowSuite subscription cannot reach the two usage endpoints; they get 403 insufficient_key_scope.

GET
/v1/credits

Retrieve credit

Returns the independent EUR account of the authenticated team, without any payment or model call.

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

Summarise usage

Summarises requests, tokens and costs for a period by day, model, key or end user.

Query parameters

start string
First day in the format YYYY-MM-DD, default 29 days before end
end string
Last day in the format YYYY-MM-DD, default today
group_by string
day, model, api_key or end_user; default day
curl -X GET "https://api.flowmodels.one/v1/usage" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/usage/requests

List individual requests

Lists individual requests with model, provider, status, runtime, token counts and cost, without request or response text.

Query parameters

limit integer
Entries per page, 1 to 100, default 20
after string
Cursor from last_id of the previous page
status string
Only requests with this status
api_key string
UUID of a key of the same workspace
end_user string
External end-user identifier
model string
Model identifier as sent in the request
curl -X GET "https://api.flowmodels.one/v1/usage/requests" \
  -H "Authorization: Bearer $FLOWMODELS_API_KEY" \
  -H "Accept: application/json"
GET
/v1/key

Check the API key in use

Returns status, key type and applicable request limits for the authenticating API key.

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

List API keys

Lists the active keys of the authenticated user in the authenticated workspace. Secret token values are never returned.

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

Create an API key

Creates a key in the authenticated workspace and returns the new token value in this response.

Request body

name string
required
Display name, at most 255 characters
kind string
inference or management; default management. Explicitly use inference for model requests
expires_at datetime
Optional expiry time in the future
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": "FlowModels production", "kind": "inference"}'
DELETE
https://creativeskyline.de/api/user/api-keys/{key_uuid}

Revoke an API key

Immediately revokes an additional key of the authenticated workspace. Personal keys can only be renewed.

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

Renew an API key

Replaces the token value of a key in the authenticated workspace. The configured grace period determines how long the previous value remains valid.

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

Limits and error handling

Observe the request limits

By default, FlowModels keys are limited to at most 4 MiB per JSON request, 1,000 messages, 1,000,000 characters per message and 128 tools in tools. The requests per minute and the concurrently running requests depend on the rate-limit tier of the workspace: 60 per minute and 10 concurrent in tier 1, 600 and 25 in tier 2 (from €5 paid), 2,000 and 50 in tier 3 (from €100) and 6,000 and 100 in tier 4 (from €500). Tiers rise automatically; for postpaid billing, billed usage counts. Further token, cost and monthly limits can apply independently. GET /key names your tier, the effective limit per minute and the limit for concurrent requests; a key can only lower its limit per minute. The tier rises automatically and does not fall on its own.

Common responses

  • 400 invalid_field_value: Check the required field, value or data type.
  • 400 unsupported_field: A field is not supported for the chosen endpoint. Check its parameter list. You get the same response for context_compression while history compression is switched off.
  • 400 context_length_exceeded: The history you sent does not fit into the model's input window. The message names max_input_tokens and estimated_input_tokens; param is messages. Send fewer messages or set context_compression: true.
  • 401 invalid_api_key: The token is missing, invalid, expired or revoked.
  • 403 insufficient_key_scope: Use a key with “Use AI”.
  • 403 account_suspended: The FlowModels access of this account is suspended. Contact support; retrying does not help.
  • 404 model_not_found: Compare the full identifier with the current model list.
  • 404 conversation_not_found: Check the workspace, the end-user identifier and the conversation UUID.
  • 409 conversation_in_progress: Wait for the previous call of the same conversation.
  • 409 idempotency_key_in_progress: The request with this idempotency key is still running, or its result is not reliably known after a failure.
  • 413 payload_too_large: Reduce the JSON request.
  • 422 idempotency_key_reuse: The same idempotency key was used for different request data.
  • 429 rate_limit_exceeded: Observe the returned waiting time.
  • 429 concurrent_requests_exceeded: As many requests are already running at the same time as the tier of the workspace allows. Send fewer requests in parallel and retry after the waiting time from Retry-After.
  • 429 insufficient_quota: Check the available credit.
  • 429 spend_limit_exceeded: The monthly key limit or an enabled credit line is not sufficient; a top-up does not change a key limit.
  • 503 routing_unavailable: FlowModels is temporarily switched off. Observe the waiting time from the Retry-After header; no credit is reserved and no provider is called.
  • 503 provider_overloaded: The provider has no capacity right now. Observe the waiting time from the Retry-After header and retry the call afterwards.
  • 400 invalid_cursor: The cursor is missing, empty or does not belong to the list being called.
  • 400 unsupported_for_model: The field is valid, but the selected model does not accept it; param names the field. Which fields a model accepts is listed in GET /models.
  • 401 invalid_token_source: The key was not sent via Authorization: Bearer.
  • 404 response_not_found: The response is unknown, expired or not stored.
  • 404 file_not_found: The file is unknown or does not belong to this workspace.
  • 404 memory_not_found: The memory or its end user was not found.
  • 404 end_user_not_found: The end user is unknown or does not belong to this workspace.
  • 404 webhook_endpoint_not_found: The webhook target is unknown or does not belong to this workspace.
  • 409 memory_revision_conflict: The memory has changed in the meantime.
  • 410 model_deprecated: The model has been retired and can no longer be called; choose a model from GET /models.
  • 413 file_too_large: The file exceeds the upload limit.
  • 429 credit_balance_exhausted: The credit is not sufficient for this request; a top-up is required.
  • 429 period_spend_limit_exceeded: The spending limit of the calendar month would be exceeded; a top-up alone does not change this limit.
  • 502 routing_execution_failed: The request could not be completed, for example because the selected provider did not answer. FlowModels does not fall back to another model; you decide whether to retry the request.
  • 503 pricing_unavailable: No reliable price is currently available for the model.

Retry safely and match errors

Use a stable Idempotency-Key per logical operation for repeated POST requests. An identical, successfully completed JSON request can be answered again within the retention window of 24 hours by default. Changed content or file names need a new key. After a connection break, paid processing may have taken place anyway, so do not automatically switch to a new key.

Errors contain error.message, error.type, error.code and, where applicable, error.param. Keep the flowai_request_id from the response for support requests.

Retention of your call logs

For every call we store a log with the time, model, token counts, runtime, status and flowai_request_id. The submitted request content and the response text are also retained for support diagnosis and deleted automatically after 30 days; the log itself is kept as proof of usage and billing for 400 days. On request, we completely disable the storage of request and response text for your workspace; the logs then only contain the technical details mentioned. Without this content, however, support can no longer trace a reported call.

Stable field names

Why some fields still say “flowai”

FlowModels used to have a different product name. The name has changed, the responses of your integration have not. Field names, error codes and protocol names are a contract with your code: renaming them would force every existing integration to change at the same time. They therefore stay the same for good and keep the word flowai.

  • flowai_request_id: Identifier of a request in every response, for example for support requests.
  • usage.flowai.*: Extra usage details, such as usage.flowai.compression.
  • flowai_limits and flowai_tools: Field names in model entries and requests.
  • error.code and error.type: Machine-readable error details. The message text in error.message can change, the code and type do not.
  • flowai-ticket.*: The WebSocket subprotocol of live transcription.

You can rely on it: these names do not change with the product name.