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.
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
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).
Top up at least €20 of prepaid credit, or use an explicitly granted postpaid credit line.
Call GET /models and pick a full model identifier.
Send model and your messages, optionally with external_identifier, to one of the two following endpoints for AI requests.
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.
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.
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.
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.
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.
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.
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.
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 (kindvideo) 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 (kindimage) 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 kindchat; any other model is rejected with 400 unsupported_for_model and parammodel 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
limitinteger
Number of entries from 1 to 100, default 100
afterstring
Model identifier from last_id of the previous page
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 paramdimensions 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
modelstring
required
Identifier of a released embedding model in the format provider/model-id
inputstring|array
required
A string or up to 2,048 strings of at most 8,192 characters each
encoding_formatstring
float (default) or base64 for little-endian Float32
dimensionsinteger
Desired vector length, if the model supports it: bge-m3 only 1024, Qwen3-VL-Embedding-8B 1 to 4096
userstring
Your own identifier of the calling end user for abuse tracing
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
modelstring
required
Identifier of a released rerank model in the format provider/model-id, currently ionos/Qwen/Qwen3-VL-Reranker-8B
querystring
required
The query, not empty, at most 8,192 characters
documentsarray
required
1 to 1,000 non-empty strings of at most 32,768 characters each, at most 1,000,000 characters in total
top_ninteger
Number of best results, at most the number of documents; 0 or no value returns all of them
return_documentsboolean
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}'
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["FLOWMODELS_API_KEY"]}',
'Accept': 'application/json',
}
payload = {
'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,
}
response = requests.post(
'https://api.flowmodels.one/v1/rerank',
headers=headers,
json=payload,
)
data = response.json()
const response = await fetch('https://api.flowmodels.one/v1/rerank', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FLOWMODELS_API_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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,
}),
});
const data = await response.json();
use Illuminate\Support\Facades\Http;
$response = Http::withToken(getenv('FLOWMODELS_API_KEY'))
->post('https://api.flowmodels.one/v1/rerank', [
'model' => 'ionos/Qwen/Qwen3-VL-Reranker-8B',
'query' => 'What is the capital of Germany?',
'documents' => array (
0 => 'Paris is the capital of France.',
1 => 'Berlin is the capital of Germany.',
),
'top_n' => 1,
'return_documents' => true,
]);
$data = $response->json();
{
"id": "01HXYZ",
"object": "rerank",
"model": "ionos/Qwen/Qwen3-VL-Reranker-8B",
"results": [
{
"index": 1,
"relevance_score": 0.6072,
"document": {
"text": "Berlin is the capital of Germany."
}
}
],
"usage": {
"prompt_tokens": 162,
"total_tokens": 162,
"cost": "0.000009",
"currency": "EUR"
},
"flowai_request_id": "01HXYZ"
}
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.
Model
File
Live
Extra information
groq/whisper-large-v3-turbo
Yes
No
Timestamps
groq/whisper-large-v3
Yes
No
Timestamps
openai/gpt-transcribe
Yes
No
Text
ionos/openai/whisper-large-v3
Yes
No
Timestamps, EU-hosted (Berlin)
openai/gpt-live-transcribe
No
Yes
Text
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.
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
modelstring
required
Released identifier provider/model-id from GET /models
languagestring
Model-dependent language code, for example de
timestampsboolean
Explicitly enable timestamps; default false
diarizeboolean
Speaker attribution; no model currently offers it, so true is rejected with HTTP 422. Default false
filefile
required
Audio file, at most 200 MiB and eight hours; observe the model limits
backgroundboolean
Required above 24 MiB or ten minutes. Response 202 with a job ID.
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.
Model
Input
Duration (seconds)
Resolution
Aspect ratio
Further fields
bytedance/seedance-2.5/text-to-video
Prompt
4 to 30
480p, 720p, 1080p
16:9, 4:3, 1:1, 3:4, 9:16, 21:9
generate_audio, output_format
bytedance/seedance-2.5/image-to-video
Image, optionally prompt and end image
4 to 30
480p, 720p, 1080p
Follows the image
generate_audio
minimax/h3/text-to-video
Prompt
5 to 15
2K
auto, adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
aigc_watermark
minimax/h3/image-to-video
Image and prompt, optionally end image
5 to 15
2K
As for text-to-video
aigc_watermark
alibaba/wan-3.0/text-to-video
Prompt
2 to 30
480p, 720p, 1080p
16:9, 4:3, 1:1, 3:4, 9:16, adaptive
generate_audio, enable_thinking, seed
alibaba/wan-3.0/image-to-video
Image and prompt, optionally end image
2 to 30
480p, 720p, 1080p
As for text-to-video
generate_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
POST /videos checks the parameters, reserves the full price of the requested seconds and answers with 202.
status is first queued, then in_progress, and finally completed, failed or cancelled. Poll at intervals of at least five seconds or use webhooks.
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.
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 statusfailed 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
modelstring
required
Released identifier from GET /models, for example bytedance/seedance-2.5/text-to-video
promptstring
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_urlstring
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_idstring
file_id of an image file this team uploaded earlier, instead of image_url
end_image_urlstring
End image, image-to-video models only. Same formats as image_url.
end_image_file_idstring
file_id of the end image, instead of end_image_url
durationinteger
Duration in seconds, range per model, see table. Default 5.
resolutionstring
Resolution per model, see table
aspect_ratiostring
Aspect ratio per model. Seedance image-to-video rejects this field.
generate_audioboolean
Generate audio. Seedance and Wan only, default true.
output_formatstring
mp4 or mov. Seedance text-to-video only.
enable_thinkingboolean
Wan only, default false. Has its own price per second.
seedinteger
Wan only, 0 to 2147483647
aigc_watermarkboolean
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
import os
import time
import uuid
import requests
headers = {'Authorization': f"Bearer {os.environ['FLOWMODELS_API_KEY']}"}
job = requests.post(
'https://api.flowmodels.one/v1/videos',
headers={**headers, 'Idempotency-Key': str(uuid.uuid4())},
json={
'model': 'bytedance/seedance-2.5/text-to-video',
'prompt': 'A paper boat on a calm lake at sunrise',
'duration': 5,
'resolution': '720p',
},
timeout=30,
).json()
while job['status'] in ('queued', 'in_progress'):
time.sleep(10)
job = requests.get(f"https://api.flowmodels.one/v1/videos/{job['id']}", headers=headers, timeout=30).json()
print(job['status'], job['content_url'])
// Keep the API key in your backend.
const headers = {
Authorization: `Bearer ${process.env.FLOWMODELS_API_KEY}`,
'Content-Type': 'application/json',
};
const created = await fetch('https://api.flowmodels.one/v1/videos', {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({
model: 'bytedance/seedance-2.5/text-to-video',
prompt: 'A paper boat on a calm lake at sunrise',
duration: 5,
resolution: '720p',
}),
});
if (!created.ok) throw new Error(`HTTP ${created.status}`);
let job = await created.json();
while (job.status === 'queued' || job.status === 'in_progress') {
await new Promise((resolve) => setTimeout(resolve, 10000));
job = await (await fetch(`https://api.flowmodels.one/v1/videos/${job.id}`, { headers })).json();
}
console.log(job.status, job.content_url);
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
$client = Http::withToken(getenv('FLOWMODELS_API_KEY'))->acceptJson();
$job = $client->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->post('https://api.flowmodels.one/v1/videos', [
'model' => 'bytedance/seedance-2.5/text-to-video',
'prompt' => 'A paper boat on a calm lake at sunrise',
'duration' => 5,
'resolution' => '720p',
])->throw()->json();
do {
sleep(10);
$job = $client->get('https://api.flowmodels.one/v1/videos/'.$job['id'])->throw()->json();
} while (in_array($job['status'], ['queued', 'in_progress'], true));
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.
Model
Sizes
Quality
Editing
openai/gpt-image-2.6-sunburst
square, portrait, landscape, 2k
low, medium
Yes
google/gemini-3.1-flash-image
square, portrait, landscape, 2k
medium
No
google/gemini-nano-banana-2.1
square, portrait, landscape, 2k
medium
No
minimax/h3-image
square, portrait, landscape, 2k
medium
Yes
minimax/h3-image-highspeed
square, portrait, landscape, 2k
medium
Yes
ionos/black-forest-labs/FLUX.2-klein-4B
square, portrait, landscape, 2k
medium
Yes
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_formaturl 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
modelstring
required
Released identifier from GET /models, for example openai/gpt-image-2.6-sunburst
promptstring
required
Description of the image, at most 4,000 characters
sizestring
square, portrait, landscape or 2k. Default square.
qualitystring
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
ninteger
Number of images, only 1 is allowed
response_formatstring
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"}'
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["FLOWMODELS_API_KEY"]}',
'Accept': 'application/json',
}
payload = {
'model': "openai/gpt-image-2.6-sunburst",
'prompt': "A paper boat on a calm lake at sunrise",
'size': "landscape",
'quality': "low",
}
response = requests.post(
'https://api.flowmodels.one/v1/images/generations',
headers=headers,
json=payload,
)
data = response.json()
const response = await fetch('https://api.flowmodels.one/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FLOWMODELS_API_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: "openai/gpt-image-2.6-sunburst",
prompt: "A paper boat on a calm lake at sunrise",
size: "landscape",
quality: "low",
}),
});
const data = await response.json();
use Illuminate\Support\Facades\Http;
$response = Http::withToken(getenv('FLOWMODELS_API_KEY'))
->post('https://api.flowmodels.one/v1/images/generations', [
'model' => 'openai/gpt-image-2.6-sunburst',
'prompt' => 'A paper boat on a calm lake at sunrise',
'size' => 'landscape',
'quality' => 'low',
]);
$data = $response->json();
Released identifier from GET /models, for example openai/gpt-image-2.6-sunburst
promptstring
required
Description of the image, at most 4,000 characters
sizestring
square, portrait, landscape or 2k. Default square.
qualitystring
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
ninteger
Number of images, only 1 is allowed
response_formatstring
url (default) or b64_json
image_urlstring
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_idstring
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"}'
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["FLOWMODELS_API_KEY"]}',
'Accept': 'application/json',
}
payload = {
'model': "openai/gpt-image-2.6-sunburst",
'prompt': "Mach daraus eine Nachtszene mit Laternen",
'image_url': "https://example.com/boot.png",
}
response = requests.post(
'https://api.flowmodels.one/v1/images/edits',
headers=headers,
json=payload,
)
data = response.json()
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
Model
Question types
Questions per request
Images
Text limit
openai/decisions/gpt-6-luna
predicate, choice, score
400
Yes
Checked by the provider
typesafe/jev-1.14.0
predicate, choice, score, box
100
Yes, PNG and JPEG
256,000 characters of input, 128,000 per question
typesafe/jev-latest
as jev-1.14.0
100
Yes, PNG and JPEG
as 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
modelstring
required
openai/decisions/gpt-6-luna, typesafe/jev-1.14.0 or typesafe/jev-latest (see GET /models, kind decision)
inputstring|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.
questionsarray
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_keystring
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"}]}]}'
import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["FLOWMODELS_API_KEY"]}',
'Accept': 'application/json',
}
payload = {
'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"}]}],
}
response = requests.post(
'https://api.flowmodels.one/v1/decisions',
headers=headers,
json=payload,
)
data = response.json()
const response = await fetch('https://api.flowmodels.one/v1/decisions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FLOWMODELS_API_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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"}]}],
}),
});
const data = await response.json();
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:
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:
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
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
messagesarray
required
New messages with role and content; at least one non-empty user message
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
max_tokensinteger
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
streamboolean
true returns Chat Completions chunks as SSE; default false
context_compressionboolean
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_effortstring
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_searchboolean
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_formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_tokensinteger
The same setting as max_tokens under the name used by the Responses API. Sending both with different values is rejected
stream_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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_filterarray
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
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
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
messagesarray
required
New messages with role and content; at least one non-empty user message
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
max_tokensinteger
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
streamboolean
true returns Chat Completions chunks as SSE; default false
context_compressionboolean
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_effortstring
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_searchboolean
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_formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_tokensinteger
The same setting as max_tokens under the name used by the Responses API. Sending both with different values is rejected
stream_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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_filterarray
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
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLOWMODELS_API_KEY"],
base_url="https://api.flowmodels.one/v1",
)
result = client.chat.completions.create(
model="groq/openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Summarize the benefits of clear project planning."}],
max_tokens=512,
stream=True,
)
for chunk in result:
print(chunk.choices[0].delta.content or "", end="", flush=True)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLOWMODELS_API_KEY,
baseURL: "https://api.flowmodels.one/v1",
});
const result = await client.chat.completions.create({
"model": "groq/openai/gpt-oss-120b",
"messages": [
{
"role": "user",
"content": "Summarize the benefits of clear project planning."
}
],
"max_tokens": 512,
"stream": true
});
for await (const chunk of result) {
process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
}
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
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
inputstring|array
required
New user message as text or a supported message structure
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
streamboolean
Receive response events as SSE; can also be combined with background
backgroundboolean
Run in the background; without stream, HTTP 202 with a response ID follows
storeboolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_iduuid
Registered webhook target for a background job
max_output_tokensinteger
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_compressionboolean
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.effortstring
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_searchboolean
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_formatobject
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.formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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
metadataobject
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_filterarray
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
Alternative with input instead of messages, synchronous, as SSE or in the background. An end-user identifier optionally adds Brain context.
Request body
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
inputstring|array
required
New user message as text or a supported message structure
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
streamboolean
Receive response events as SSE; can also be combined with background
backgroundboolean
Run in the background; without stream, HTTP 202 with a response ID follows
storeboolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_iduuid
Registered webhook target for a background job
max_output_tokensinteger
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_compressionboolean
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.effortstring
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_searchboolean
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_formatobject
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.formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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
metadataobject
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_filterarray
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}'
import os
from urllib.request import Request, urlopen
request = Request("https://api.flowmodels.one/v1/responses", 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}".encode("utf-8"), headers={"Authorization": f"Bearer {os.environ['FLOWMODELS_API_KEY']}", "Content-Type": "application/json", "Accept": "text/event-stream"}, method="POST")
with urlopen(request) as response:
for line in response:
print(line.decode('utf-8'), end='')
const response = await fetch("https://api.flowmodels.one/v1/responses", {"method":"POST","headers":{"Authorization":`Bearer ${process.env.FLOWMODELS_API_KEY}`,"Content-Type":"application/json","Accept":"text/event-stream"},"body":"{\"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}"});
if (!response.ok) throw new Error(await response.text());
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value, { stream: true }));
}
Starts a stored background job and answers with HTTP 202. Use the response ID for polling, SSE and cancellation.
Request body
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
inputstring|array
required
New user message as text or a supported message structure
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
streamboolean
Receive response events as SSE; can also be combined with background
backgroundboolean
Run in the background; without stream, HTTP 202 with a response ID follows
storeboolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_iduuid
Registered webhook target for a background job
max_output_tokensinteger
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_compressionboolean
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.effortstring
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_searchboolean
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_formatobject
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.formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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
metadataobject
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_filterarray
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
Combines background and stream. The worker keeps running if the observation stream is interrupted.
Request body
modelstring
required
Full identifier from GET /models in the format provider/model-id
external_identifierstring
Enables Brain context for your stable end-user identifier of 1 to 255 characters, sent in the JSON body
inputstring|array
required
New user message as text or a supported message structure
conversationuuid
UUID from the previous response of the same end user; omit it for a new conversation
streamboolean
Receive response events as SSE; can also be combined with background
backgroundboolean
Run in the background; without stream, HTTP 202 with a response ID follows
storeboolean
Keep the response and its events retrievable for 24 hours after completion; default true with background, otherwise false
webhook_endpoint_iduuid
Registered webhook target for a background job
max_output_tokensinteger
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_compressionboolean
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.effortstring
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_searchboolean
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_formatobject
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.formatobject
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
toolsarray
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_choicestring|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_callsboolean
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_optionsobject
Accepts include_usage only and requires stream: true. With include_usage: true a final chunk reports the usage of the streamed response
userstring
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
metadataobject
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_filterarray
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}'
import os
from urllib.request import Request, urlopen
request = Request("https://api.flowmodels.one/v1/responses", 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}".encode("utf-8"), headers={"Authorization": f"Bearer {os.environ['FLOWMODELS_API_KEY']}", "Content-Type": "application/json", "Accept": "text/event-stream"}, method="POST")
with urlopen(request) as response:
for line in response:
print(line.decode('utf-8'), end='')
const response = await fetch("https://api.flowmodels.one/v1/responses", {"method":"POST","headers":{"Authorization":`Bearer ${process.env.FLOWMODELS_API_KEY}`,"Content-Type":"application/json","Accept":"text/event-stream"},"body":"{\"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}"});
if (!response.ok) throw new Error(await response.text());
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value, { stream: true }));
}
import os
from urllib.request import Request, urlopen
request = Request("https://api.flowmodels.one/v1/responses/{response_uuid}?stream=true&starting_after=4", data=None, headers={"Authorization": f"Bearer {os.environ['FLOWMODELS_API_KEY']}", "Content-Type": "application/json", "Accept": "text/event-stream"}, method="GET")
with urlopen(request) as response:
for line in response:
print(line.decode('utf-8'), end='')
const response = await fetch("https://api.flowmodels.one/v1/responses/{response_uuid}?stream=true&starting_after=4", {"method":"GET","headers":{"Authorization":`Bearer ${process.env.FLOWMODELS_API_KEY}`,"Content-Type":"application/json","Accept":"text/event-stream"}});
if (!response.ok) throw new Error(await response.text());
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value, { stream: true }));
}
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.
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
filefile
required
Supported text or document file with a file name of up to 255 characters
purposestring
required
Required value user_data; other purposes are rejected
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.
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. Withoutquery 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. Withquery, 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.
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
urlstring
required
Publicly reachable HTTPS address, at most 2,048 characters
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.
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.
Cookies and statistics
We use necessary cookies so that FlowModels works. With your consent we also measure with Google Analytics through Google Tag Manager how the pages are used. Data may be transferred to Google in the USA. You can change or withdraw your choice at any time via “Cookie settings” in the footer.
Privacy policy
Your choice could not be saved. Please reload the page and try again.
Show providers and cookies
Necessary
Session and form protection
Creative Skyline (this website)
Keeps your session open, for example for sign-in, cart and forms, and protects forms against forged requests (CSRF).
Only on pages with a protected form. The script is loaded from challenges.cloudflare.com; Cloudflare processes your IP address and technical features of your browser. Transfers to the USA are based on the EU-US Data Privacy Framework.
No cookies on this website
Stripe
Stripe Payments Europe, Limited, Ireland
Processes card payments and direct debits and detects fraud.
Only on pages where you make a payment or set up a payment method. Stripe, Inc. may process data in the USA; this is based on the EU-US Data Privacy Framework.
__stripe_mid: 1 year
__stripe_sid: 30 minutes
Statistics
Google Tag Manager and Google Analytics
Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Reach measurement: through Google Tag Manager we load Google Analytics 4, which measures which pages are visited how often and for how long, where visitors come from and which devices they use. Tag Manager itself sets no cookies.
Only loaded after your consent (Google Consent Mode, everything is denied before, advertising storage stays denied). Data may be transferred to Google LLC in the USA based on the EU-US Data Privacy Framework. When you withdraw, we delete the Analytics cookies.