مستندات
مرجع API
آدرس پایه https://ai.fluxcdn.cloud/api/v1 است. ساختار درخواست و پاسخ سازگار با OpenAI است، بنابراین یک کلاینت موجود تنها با تغییر آدرس پایه و کلید کار میکند. دادهٔ اختصاصی فلاکسسیدیان همیشه افزودنی است — هیچ فیلد OpenAI معنایش عوض نمیشود.
اندپوینتها
| اندپوینت | هدف | وضعیت |
|---|---|---|
| GET /v1/models | فهرست مدلهایی که این کلید به آنها دسترسی دارد. | فعال |
| POST /v1/chat/completions | تکمیل گفتوگو، با و بدون پخش زنده. | فعال |
| POST /v1/videos | ساخت ویدئو. ناهمگام: پاسخ، یک کار است که وضعیتش را میپرسید. | فعال |
| GET /v1/videos/{id} | وضعیت یک کار ویدئو؛ کارهای کاملشده نشانی محتوایشان را دارند. | فعال |
| GET /v1/videos/{id}/content | ویدئوی آماده، بهصورت جریانی (MP4). | فعال |
| POST /v1/messages | Messages سازگار با Anthropic، با و بدون پخش زنده، با هر مدلی: برای Claude Code و SDKهای Anthropic (آدرس پایه https://ai.fluxcdn.cloud/api). | فعال |
| POST /v1/messages/count_tokens | تخمین تعداد توکنهای ورودی یک درخواست Messages (رایگان). | فعال |
| POST /v1/responses | Responses سازگار با OpenAI، بدون نگهداری وضعیت، با و بدون پخش زنده، با هر مدلی: برای Codex و responses.create در SDKهای OpenAI. | فعال |
| POST /v1/embeddings | بردارسازی متن (embedding) با ساختار OpenAI (همان embeddings.create)، با مدلهای بردارسازی کاتالوگ. | فعال |
| POST /v1/rerank | مرتبکردن اسناد بر اساس ربطشان به یک پرسش (ساختار Cohere)؛ هزینهای که هر پاسخ گزارش میکند بهاضافهٔ سود طرح شما. | فعال |
| POST /v1/images/generations | ساخت تصویر با ساختار OpenAI (همان images.generate)، با هر مدل تصویری؛ خروجی بهصورت b64_json. | فعال |
| POST /v1/images/edits | ویرایش یا ترکیب تصویر با ساختار OpenAI (همان images.edit). | فعال |
| POST /v1/audio/speech | تبدیل متن به گفتار با ساختار OpenAI (همان audio.speech.create): مدلهای متن به گفتار (ElevenLabs، Grok Voice، MiniMax، Gemini و…) بهصورت MP3، WAV یا PCM و به ازای هر نویسه؛ GPT Audio بهصورت WAV یا PCM. | فعال |
| POST /v1/audio/transcriptions | تبدیل گفتار به متن با ساختار OpenAI (همان audio.transcriptions.create): json، text، srt، vtt یا verbose_json با زمانبندی جملهها و کلمهها. | فعال |
احراز هویت
توکن Bearer روی هر درخواست. کلیدها را فلاکسسیدیان صادر میکند، به یک پروژه محدودند و دقیقاً یکبار هنگام ساخت بهطور کامل نمایش داده میشوند.
Authorization: Bearer flux_live_YOUR_KEYهدرهای پاسخ
روی هر پاسخ، از جمله پخش زنده و خطاها، تنظیم میشوند. کلاینتها میتوانند به آنها تکیه کنند.
- x-fluxcdn-request-id
- با سطر مربوطه در بخش فعالیت مطابقت دارد. در درخواستهای پشتیبانی آن را ذکر کنید.
- x-fluxcdn-resolved-model
- مدلی که واقعاً سرویس داده؛ وقتی از نام مستعار استفاده شده باشد با مدل درخواستی فرق دارد.
- x-fluxcdn-provider
- همیشه fluxcdn: هر درخواست روی حسابهای خود FluxCDN سرویس داده میشود. سازندهٔ مدل بخش نخست شناسهٔ مدل است.
- x-fluxcdn-region
- همیشه global.
- x-fluxcdn-attempts
- تعداد اندپوینتهای امتحانشده. عدد بیشتر از ۱ یعنی مسیر جایگزین استفاده شده است.
- x-fluxcdn-cost-micros
- هزینهٔ درخواست برای شما، به میکرو صحیح.
پخش زنده
با تنظیم stream روی true، پاسخ بهصورت رویدادهای ارسالی از سرور در قالب چانک OpenAI میآید و با data: [DONE] پایان مییابد. مصرف و تصمیم مسیریابی در آخرین چانک، پیش از پایاندهنده، میرسند.
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]تصویر، PDF، صوت و ویدئو
محتوای پیام کاربر میتواند بهجای یک رشته، فهرستی از بخشها باشد، با همان ساختاری که OpenAI تعریف کرده: متن، تصویر، فایل، صوت و ویدئو. هر کدام را به مدلی بفرستید که input_modalities آن شامل همان نوع باشد (GET /v1/models یا صفحهٔ مدل)؛ در غیر این صورت درخواست پیش از هر هزینهای با invalid_request و نام همان بخش رد میشود.
| بخش | ساختار | توضیح |
|---|---|---|
| image_url | {"type": "image_url", "image_url": {"url": "https://…/photo.jpg"}} | یک لینک https یا یک data URL، با قالب PNG، JPEG، WebP یا GIF. فیلد detail اختیاری است. |
| file | {"type": "file", "file": {"filename": "report.pdf", "file_data": "data:application/pdf;base64,…"}} | یک PDF بهصورت data URL (data:application/pdf;base64,…) یا لینک https، با نام فایل اختیاری. مدلهایی که ورودی فایل را فهرست کردهاند آن را مستقیم میخوانند. |
| input_audio | {"type": "input_audio", "input_audio": {"data": "<base64>", "format": "mp3"}} | صوت base64 همراه با قالبش (wav، mp3، m4a، ogg، flac و …). برای صوت لینک پذیرفته نمیشود. |
| video_url | {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,…"}} | یک data URL (mp4، mov، webm و …) یا لینکی که مدل پشتیبانی میکند (برای Gemini، لینک YouTube). |
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"}}
]
}]
}'ورودی ویدئو فقط روی مدلهایی کار میکند که input_modalities آنها شامل video باشد، مثل مدلهای Gemini. مدلهای Claude تصویر و PDF میپذیرند، نه ویدئو. برای ساخت ویدئو، بخش «ساخت ویدئو» را در ادامه ببینید.
{
"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 را بفرستید (تابعهایی با JSON Schema آرگومانهایشان) و در صورت نیاز tool_choice و parallel_tool_calls را. مدل با tool_calls و finish_reason برابر tool_calls پاسخ میدهد؛ تابع را اجرا کنید، سپس پیام assistant را همراه یک پیام tool که نتیجه و tool_call_id را دارد برگردانید. در حالت پخش زنده، فراخوانیها بهصورت delta میآیند و index میگوید هر تکه از arguments مال کدام فراخوانی است. فقط ابزارهای تابعی منتقل میشوند؛ مدلی که ابزار ندارد رد میشود.
{
"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 و خروجی ساختاریافته
مقدار response_format: {"type": "json_object"} یک شیء JSON میخواهد؛ {"type": "json_schema", "json_schema": {"name", "schema", "strict"}} پاسخی میخواهد که از اسکیمای شما پیروی کند، روی مدلهایی که structured_outputs را فهرست کردهاند.
"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
}
}
}ساخت و ویرایش تصویر
یک مدل تصویری (در صفحهاش نوشته «تصویر میسازد») را با یک پرامپت صدا بزنید. تصویرها روی choices[0].message.images بهصورت data URL برمیگردند ({type: "image_url", image_url: {url}}) و در پخش زنده روی delta.images. API بهطور پیشفرض تصویر میخواهد؛ modalities: ["text"] فقط متن میخواهد. برای ویرایش، تصویر را بهصورت یک بخش تصویر همراه با دستورتان بفرستید. گزینههایی مثل image_config: {"aspect_ratio": "16:9"} به مدلهایی که آنها را میپذیرند منتقل میشوند. توکنهای تصویر با قیمت تصویر همان مدل (در صفحهاش) حساب میشوند. اگر کدتان برای images.generate در OpenAI نوشته شده، میتوانید بهجای این راه از /v1/images/generations استفاده کنید (پایینتر).
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,…"}}
]تصویر با ساختار OpenAI
اندپوینت POST /v1/images/generations همان درخواست OpenAI را میپذیرد (model، prompt، n، size، user و stream)، پس `client.images.generate(...)` با هر مدل تصویریِ فهرست کار میکند. نامهای خود OpenAI (مثل gpt-image-1 و dall-e-3) به مدلهای ما خوانده میشوند و اگر مدلی ندهید، google/gemini-3.1-flash-image به کار میرود. `size` به نزدیکترین قابی که مدل میسازد تبدیل میشود. تصویر فقط بهصورت `b64_json` برمیگردد: اینجا چیزی نگه داشته نمیشود که لینکی داشته باشد، پس `response_format: "url"` رد میشود. برای ویرایش، POST /v1/images/edits تصویرها را همراه دستور شما میگیرد (بهصورت فایل، همانطور که SDKها میفرستند، یا `images: [{image_url}]`)؛ ماسک پشتیبانی نمیشود.
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هر تصویری که میخواهید (`n`، حداکثر ۴) یک درخواست تکمیل گفتوگو به مدل تصویری است و دقیقاً بهاندازهٔ همان درخواست هزینه دارد: `x-fluxcdn-request-id` شناسهٔ همهٔ آنها را دارد و `x-fluxcdn-cost-micros` جمع هزینهشان را. `quality`، `style` و `output_format` پذیرفته میشوند، ولی انتخابشان با خود مدل است؛ `output_format` در پاسخ میگوید چه قالبی آمده. اگر مدل بهجای تصویر فقط متن بنویسد، همان پاسخ مثل هر درخواست تکمیل گفتوگو حساب میشود و شما خطای 400 با کد `no_image` و حرف خود مدل را میگیرید.
تبدیل متن به گفتار
اندپوینت POST /v1/audio/speech همان درخواست OpenAI را میپذیرد (model، input، voice، instructions، response_format، speed و stream_format)، پس `client.audio.speech.create(...)` کار میکند. tts-1، tts-1-hd و gpt-4o-mini-tts به openai/gpt-audio-mini (پیشفرض) خوانده میشوند؛ برای صدای بزرگتر، openai/gpt-audio را با نام خودش بخواهید. صدا متنِ `input` را عیناً و کلمهبهکلمه میخواند، تا ۴٬۰۹۶ نویسه و به هر زبانی که بلد است؛ `instructions` فقط حالت و لحن گفتن را تعیین میکند، نه کلمهها را. صدا همزمان با ساختهشدن فرستاده میشود: بهصورت WAV (پیشفرض اینجا) یا PCM خام (۲۴ کیلوهرتز، ۱۶ بیتی، تککاناله)، یا با `stream_format: "sse"` بهصورت رویدادهای `speech.audio.delta`.
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 و flac ساخته نمیشوند و با خطای 400 رد میشوند؛ WAV بخواهید و اگر لازم بود خودتان تبدیلش کنید. `speed` با کلمه از گوینده خواسته میشود و صدا کش نمیآید. WAVِ جریانی، مثل هر WAV جریانی دیگر، طول خود را «نامعلوم» اعلام میکند و پخشکنندهها آن را تا انتها میخوانند. هزینه همان هزینهٔ درخواست تکمیل گفتوگوی جریانیای است که ساخته میشود: متنِ ورودی، و کلمهها و صدای خروجی با قیمت صدای همان مدل.
ساخت ویدئو
مدلهای ویدئویی (output_modalities برابر ["video"]؛ صفحهٔ هر کدام مدتها، کیفیتها، نسبتهای تصویر و قیمت هر ثانیه را نشان میدهد) از راه POST /v1/videos صدا زده میشوند: با prompt و در صورت پشتیبانی مدل duration، resolution یا size، aspect_ratio، generate_audio، seed، frame_images (first_frame یا last_frame) و input_references (تصویر). پاسخ 202 است با شناسهٔ کار (vid_…). هر چند ثانیه GET /v1/videos/{id} را بپرسید: pending، in_progress و سپس completed — همراه content_urls — یا failed، cancelled یا expired. GET /v1/videos/{id}/content فایل MP4 را بهصورت جریانی میدهد (درخواست range هم کار میکند). مقداری که مدل نمیپذیرد با فهرست مقادیر مجاز رد میشود. اگر duration و resolution را ندهید، کوتاهترین مدت و پایینترین کیفیت مدل انتخاب میشود.
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."}}قیمت هر ثانیه برای کیفیت انتخابی (و صدا، اگر قیمت را تغییر دهد) هنگام ارسال ثابت میشود و رزرو، بیشترین حالت را نگه میدارد. وقتی ویدئو آماده شد یکبار کسر میشود — ثانیههایش با همان قیمت، بهعلاوهٔ تصویرهای ورودی اگر مدل برایشان هزینه بگیرد — و بقیه آزاد میشود. ویدئویی که ناموفق، لغو یا منقضی شود هزینهای ندارد. اعتبار آزمایشی برای ویدئو پرداخت نمیکند.
حداکثر ۳ ویدئو در حال ساخت همزمان در هر فضای کاری و ۶ ویدئوی جدید در دقیقه برای هر کلید؛ مدت، کیفیت و نسبت تصویر همانهایی که مدل فهرست کرده؛ حداکثر ۲ تصویر فریم و ۴ تصویر مرجع، هر کدام تا ۱۰ مگابایت. وبهوک (callback_url) و گزینههای اختصاصی ارائهدهنده منتقل نمیشوند.
پارامترهای دیگر
seed، frequency_penalty، presence_penalty، stop، logprobs و top_logprobs، reasoning (با effort یا max_tokens) و reasoning_effort، user، temperature، top_p و max_tokens (یا max_completion_tokens). پارامتر نمونهبرداریای که مدل نمیپذیرد، مثل خود سرویس بالادستی، نادیده گرفته میشود؛ ابزار، JSON، logprobs و پیوستها بررسی میشوند و اگر مدل آنها را نداشته باشد رد میشوند. n باید ۱ باشد. فیلدهای دیگر (پلاگینها و ابزارهای سمت سرور خود ارائهدهنده) منتقل نمیشوند.
محدودیتها
- بدنهٔ درخواست: حداکثر ۲۵ مگابایت. فایلهای بزرگ را بهصورت لینک https بفرستید.
- حداکثر ۲۰ پیوست در هر درخواست، هر کدام حداکثر ۲۰ مگابایت پس از رمزگشایی.
- حداکثر ۱۲۸ ابزار.
- لینکها باید https:// باشند.
- یک پاسخ در هر درخواست (n = 1).
واحدهای اضافه چگونه حساب میشوند
پیوستها بهاندازهٔ توکنهای ورودیای که ارائهدهنده برایشان میشمارد حساب میشوند، تصویرهای ساختهشده بهصورت توکن تصویر با قیمت تصویر مدل، و نوشتن در کش با قیمت خودش؛ خواندن از کش با همان قیمت عادی ورودی حساب میشود. رزرو پیش از هر فراخوانی برای هر پیوست و برای یک تصویر ساختهشده سهمی کنار میگذارد و هنگام تسویه آزاد میشود.
قرارداد خطا
هر شکست بالادستی به یک ساختار و یک مجموعهٔ بستهٔ انواع نگاشت میشود، بنابراین منطق تلاش دوباره به شاخهای جداگانه برای هر فروشنده نیاز ندارد. پرچم retryable میگوید آیا تکرار عیناً همان درخواست میتواند موفق شود یا نه. insufficient_credit همیشه یعنی کیف پول خود شما؛ وقتی مدلی مدتی نتواند درخواست بپذیرد، پاسخ upstream_unavailable است (۵۰۳، همراه با Retry-After) و هزینهای کسر نمیشود: کمی بعد دوباره بفرستید یا مدل دیگری انتخاب کنید.
{
"error": {
"type": "upstream_unavailable",
"message": "All endpoints for this model are unavailable.",
"request_id": "req_8Kd2Qm",
"retryable": true,
"attempts": 3
}
}| نوع | HTTP | قابل تلاش مجدد |
|---|---|---|
| invalid_request | 400 | خیر |
| invalid_api_key | 401 | خیر |
| insufficient_credit | 402 | خیر |
| policy_violation | 403 | خیر |
| content_blocked | 400 | خیر |
| model_not_found | 404 | خیر |
| not_found | 404 | خیر |
| context_length_exceeded | 400 | خیر |
| rate_limit_exceeded | 429 | بله |
| budget_exceeded | 429 | خیر |
| internal_error | 500 | خیر |
| upstream_error | 502 | بله |
| upstream_unavailable | 503 | بله |
| upstream_timeout | 504 | بله |

