Skip to content
FluxCDNFluxCDN
esc
On this page

Docs

API reference

Base URL https://ai.fluxcdn.cloud/api/v1. Request and response shapes are OpenAI-compatible, so an existing client works by changing only the base URL and the key. FluxCDN-specific data is additive — no OpenAI field ever changes meaning.

Endpoints

EndpointPurposeStatus
GET /v1/modelsList models this key can reach.Live
POST /v1/chat/completionsChat completions, streaming and non-streaming.Live
POST /v1/videosCreate a video. Asynchronous: answers with a job to poll.Live
GET /v1/videos/{id}A video job's status; completed jobs list their content URLs.Live
GET /v1/videos/{id}/contentThe finished video, streamed (MP4).Live
POST /v1/messagesAnthropic-compatible Messages, streaming and non-streaming, with any model: Claude Code and the Anthropic SDKs (base address https://ai.fluxcdn.cloud/api).Live
POST /v1/messages/count_tokensAbout how many input tokens a Messages request is (free).Live
POST /v1/responsesOpenAI Responses, stateless, streaming and non-streaming, with any model: Codex and the OpenAI SDKs' responses.create.Live
POST /v1/embeddingsText embeddings in OpenAI's shape (embeddings.create) with the catalog's embedding models.Live
POST /v1/rerankDocuments ranked against a query (Cohere's shape), charged what each answer reports plus your plan's margin.Live
POST /v1/images/generationsImages in OpenAI's shape (images.generate) with any image model, as b64_json.Live
POST /v1/images/editsEdit or combine pictures in OpenAI's shape (images.edit).Live
POST /v1/audio/speechText to speech in OpenAI's shape (audio.speech.create): text-to-speech models (ElevenLabs, Grok Voice, MiniMax, Gemini…) as MP3, WAV or PCM, billed per character; GPT Audio as WAV or PCM.Live
POST /v1/audio/transcriptionsSpeech to text in OpenAI's shape (audio.transcriptions.create): json, text, srt, vtt or verbose_json with segment and word times.Live

Authentication

Bearer token on every request. Keys are issued by FluxCDN, scoped to one project, and shown in full exactly once at creation.

HTTP
Authorization: Bearer flux_live_YOUR_KEY

Response headers

Set on every response, including streams and errors. Clients may depend on them.

x-fluxcdn-request-id
Correlates with the row in Activity. Quote it in support requests.
x-fluxcdn-resolved-model
The concrete model served, which differs from the request when an alias was used.
x-fluxcdn-provider
Always fluxcdn: every request is served on FluxCDN's own accounts. The model's maker is the first part of the model id.
x-fluxcdn-region
Always global.
x-fluxcdn-attempts
How many endpoints were tried. Greater than 1 means a failover happened.
x-fluxcdn-cost-micros
What the request cost you, in integer micros.

Streaming

With stream true the response is server-sent events in OpenAI's chunk format, terminated by data: [DONE]. Usage and the routing decision arrive on the final chunk before the terminator.

text/event-stream
data: {"id":"chatcmpl_…","object":"chat.completion.chunk",
       "choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl_…","object":"chat.completion.chunk",
       "choices":[{"index":0,"delta":{},"finish_reason":"stop"}],
       "usage":{"prompt_tokens":12,"completion_tokens":48,"total_tokens":60},
       "routing":{"resolved_model":"anthropic/claude-sonnet-4.5","provider":"fluxcdn",
                  "region":"global","attempts":1,"customer_cost_micros":756}}

data: [DONE]

Images, PDFs, audio and video

A user message's content can be a list of parts instead of a string, in the shapes OpenAI defined: text, images, files, audio and video. Send each to a model whose input_modalities include it (GET /v1/models, or the model's page); anything else is refused with invalid_request, naming the part, before anything is charged.

PartShapeNotes
image_url{"type": "image_url", "image_url": {"url": "https://…/photo.jpg"}}An https link or a data URL: PNG, JPEG, WebP or GIF. `detail` is optional.
file{"type": "file", "file": {"filename": "report.pdf", "file_data": "data:application/pdf;base64,…"}}A PDF as a data URL (data:application/pdf;base64,…) or an https link, with an optional filename. Read natively by models that list file input.
input_audio{"type": "input_audio", "input_audio": {"data": "<base64>", "format": "mp3"}}Base64 audio with its format (wav, mp3, m4a, ogg, flac, …). Links are not accepted for audio.
video_url{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,…"}}A data URL (mp4, mov, webm, …) or a link the model supports (for Gemini, YouTube links).
cURL
curl https://ai.fluxcdn.cloud/api/v1/chat/completions \
  -H "Authorization: Bearer $FLUXCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarise this contract and describe the photo."},
        {"type": "file", "file": {"filename": "contract.pdf", "file_data": "data:application/pdf;base64,JVBERi0x…"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/site.jpg"}}
      ]
    }]
  }'

Video input works only on models whose input_modalities include video, such as the Gemini models. Claude models take images and PDFs, not video. To create a video, see "Creating videos" below.

JSON
{
  "model": "google/gemini-2.5-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What happens in this clip?"},
      {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,AAAAIGZ0eXBpc29t…"}}
    ]
  }]
}

Tools (function calling)

Pass `tools` (functions with a JSON Schema of their arguments), optionally `tool_choice` and `parallel_tool_calls`. The model answers with `tool_calls` and finish_reason tool_calls; run the function, then send the assistant message back with a `tool` message carrying the result and its `tool_call_id`. Streamed, tool calls arrive as deltas whose `index` says which call a fragment of `arguments` belongs to. Only function tools are passed through; a model without tools is refused.

JSON
{
  "model": "openai/gpt-5-mini",
  "messages": [{"role": "user", "content": "What is the weather in Tehran?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }]
}

→ "finish_reason": "tool_calls",
  "message": {"role": "assistant", "content": null, "tool_calls": [
    {"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"Tehran\"}"}}
  ]}

Then send back:
  {"role": "assistant", "content": null, "tool_calls": [ …as received… ]},
  {"role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 21}"}

JSON mode and structured outputs

`response_format: {"type": "json_object"}` asks for one JSON object; `{"type": "json_schema", "json_schema": {"name", "schema", "strict"}}` for an answer that follows your schema, on models that list structured_outputs.

JSON
"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "invoice",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {"total": {"type": "number"}, "currency": {"type": "string"}},
      "required": ["total", "currency"],
      "additionalProperties": false
    }
  }
}

Creating and editing images

Call an image model (its page says "Creates images") with a prompt. The images come back on `choices[0].message.images` as data URLs (`{type: "image_url", image_url: {url}}`), and streamed on `delta.images`. The API asks for images by default; `modalities: ["text"]` asks for text only. To edit, send the picture as an image part with your instruction. Options such as `image_config: {"aspect_ratio": "16:9"}` are passed to models that take them. Image tokens are billed at the model's image price (shown on its page). Code written for OpenAI's images.generate can use /v1/images/generations instead (below).

cURL
curl https://ai.fluxcdn.cloud/api/v1/chat/completions \
  -H "Authorization: Bearer $FLUXCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "messages": [{"role": "user", "content": "A watercolour of Mount Damavand at sunrise"}],
    "modalities": ["image", "text"],
    "image_config": {"aspect_ratio": "16:9"}
  }'

→ "message": {
    "role": "assistant",
    "content": "Here is the painting.",
    "images": [{"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo…"}}]
  }

Editing: send the picture as an image part with the instruction —
  "content": [
    {"type": "text", "text": "Make the sky stormy"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,…"}}
  ]

Images in OpenAI's shape

POST /v1/images/generations takes OpenAI's request (model, prompt, n, size, user, stream), so `client.images.generate(...)` works with any image model in the catalog. OpenAI's names (gpt-image-1, dall-e-3 and the like) are read as ours, and with no model you get google/gemini-3.1-flash-image. `size` becomes the nearest shape the model makes. Images come back as `b64_json` only: nothing is kept here, so there is no link to give, and `response_format: "url"` is refused. POST /v1/images/edits takes the pictures (as files, the way the SDKs send them, or `images: [{image_url}]`) with your instruction; masks are not supported.

cURL
curl https://ai.fluxcdn.cloud/api/v1/images/generations \
  -H "Authorization: Bearer $FLUXCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A watercolour of Mount Damavand at sunrise",
    "size": "1536x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > damavand.png

Each image you ask for (`n`, at most 4) is one chat completion to the image model and costs exactly what that chat completion costs: `x-fluxcdn-request-id` lists each one and `x-fluxcdn-cost-micros` their total. `quality`, `style` and `output_format` are accepted, but the model chooses them; `output_format` in the answer says what came. If the model answers in words without an image, that answer is charged like any chat completion and you get a 400 with code `no_image` and the model's words.

Text to speech

POST /v1/audio/speech takes OpenAI's request (model, input, voice, instructions, response_format, speed, stream_format), so `client.audio.speech.create(...)` works. tts-1, tts-1-hd and gpt-4o-mini-tts are read as openai/gpt-audio-mini (the default); ask for openai/gpt-audio by name for the larger voice. The voice reads `input` exactly, word for word, up to 4,096 characters, in any language it speaks; `instructions` shape how it sounds, never the words. The sound is sent while it is being made: as WAV (the default here) or raw PCM (24 kHz, 16-bit, mono), or as `speech.audio.delta` events with `stream_format: "sse"`.

cURL
curl https://ai.fluxcdn.cloud/api/v1/audio/speech \
  -H "Authorization: Bearer $FLUXCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-audio-mini",
    "voice": "coral",
    "input": "سلام! به هوش مصنوعی FluxCDN خوش آمدید."
  }' -o welcome.wav

mp3, opus, aac and flac are not made: they are refused with a 400, so ask for WAV and convert it if you need to. `speed` is asked of the voice in words; the sound is not stretched. A streamed WAV gives its length as unknown, like any streamed WAV, and players read it to the end. It costs what the streamed chat completion it becomes costs: the text in, and the words and sound out at the model's sound price.

Creating videos

Video models (output_modalities ["video"]; their pages list durations, resolutions, aspect ratios and the price per second) are asked through POST /v1/videos with a prompt and, where the model takes them, duration, resolution or size, aspect_ratio, generate_audio, seed, frame_images (first_frame / last_frame) and input_references (images). The answer is 202 with a job id (vid_…). Poll GET /v1/videos/{id} every few seconds: pending, in_progress, then completed — with content_urls — or failed, cancelled or expired. GET /v1/videos/{id}/content streams the MP4 (range requests work). A value the model does not take is refused with the ones it does. Unset duration and resolution default to the model's shortest and lowest.

cURL
curl https://ai.fluxcdn.cloud/api/v1/videos \
  -H "Authorization: Bearer $FLUXCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1-fast",
    "prompt": "A slow aerial shot over Mount Damavand at sunrise, clouds below the peak",
    "duration": 6,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": false
  }'

→ 202 {"id": "vid_k2…", "object": "video", "status": "pending",
       "polling_url": "https://ai.fluxcdn.cloud/api/v1/videos/vid_k2…", "estimated_cost_micros": 772260}

curl https://ai.fluxcdn.cloud/api/v1/videos/vid_k2… -H "Authorization: Bearer $FLUXCDN_API_KEY"
→ {"status": "completed", "duration": 6, "resolution": "1080p",
   "content_urls": ["https://ai.fluxcdn.cloud/api/v1/videos/vid_k2…/content?index=0"], "cost_micros": 772260}

curl https://ai.fluxcdn.cloud/api/v1/videos/vid_k2…/content -H "Authorization: Bearer $FLUXCDN_API_KEY" -o damavand.mp4

Starting from a picture (image-to-video):
  "frame_images": [{"type": "image_url", "image_url": {"url": "data:image/png;base64,…"}, "frame_type": "first_frame"}]

A value the model does not take:
→ 400 {"error": {"type": "invalid_request", "param": "duration",
        "message": "google/veo-3.1-fast makes videos of 4, 6, 8 seconds."}}

The price per second for the resolution (and sound, where it changes it) is frozen when you submit; the reservation holds it for the longest case. When the video is ready you are charged once — its seconds at that price, plus input images where the model charges for them — and the rest is released. A video that fails, is cancelled or expires costs nothing. Trial credit does not pay for video.

At most 3 videos rendering at once per workspace and 6 new videos a minute per key; durations, resolutions and aspect ratios as the model lists them; at most 2 frame images and 4 reference images, each up to 10 MB. Webhooks (callback_url) and provider options are not passed through.

Other parameters

seed, frequency_penalty, presence_penalty, stop, logprobs and top_logprobs, reasoning ({effort} or {max_tokens}) and reasoning_effort, user, temperature, top_p, max_tokens (or max_completion_tokens). A sampling parameter a model does not take is ignored, as upstream; tools, JSON, logprobs and attachments are checked and refused when the model lacks them. n must be 1. Other fields (the provider's own plugins and server tools) are not passed through.

Limits

  • Request body: at most 25 MB. Send large files as https links.
  • At most 20 attachments per request, each at most 20 MB decoded.
  • At most 128 tools.
  • Links must be https://.
  • One choice per request (n = 1).

How the extra units are billed

Attachments are billed as the input tokens the provider counts for them, generated images as image tokens at the model's image price, cache writes at their own price; cached reads are billed at the normal input price. The reservation before a call includes an allowance for each attachment and for one generated image, and is released when the call settles.

Error contract

Every upstream failure is normalized to one shape and one closed set of types, so retry logic needs no branch per vendor. The retryable flag tells you whether an identical retry could plausibly succeed. insufficient_credit always means your own wallet; when a model cannot take requests for a while, the answer is upstream_unavailable (503, with Retry-After) and nothing is charged: retry later or choose another model.

JSON
{
  "error": {
    "type": "upstream_unavailable",
    "message": "All endpoints for this model are unavailable.",
    "request_id": "req_8Kd2Qm",
    "retryable": true,
    "attempts": 3
  }
}
TypeHTTPRetryable
invalid_request400no
invalid_api_key401no
insufficient_credit402no
policy_violation403no
content_blocked400no
model_not_found404no
not_found404no
context_length_exceeded400no
rate_limit_exceeded429yes
budget_exceeded429no
internal_error500no
upstream_error502yes
upstream_unavailable503yes
upstream_timeout504yes