پرش به محتوا
FluxCDNFluxCDN
esc
ورود
در این صفحه

مستندات

مرجع 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/messagesMessages سازگار با Anthropic، با و بدون پخش زنده، با هر مدلی: برای Claude Code و SDKهای Anthropic (آدرس پایه https://ai.fluxcdn.cloud/api).فعال
POST /v1/messages/count_tokensتخمین تعداد توکن‌های ورودی یک درخواست Messages (رایگان).فعال
POST /v1/responsesResponses سازگار با 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 روی هر درخواست. کلیدها را فلاکس‌سی‌دی‌ان صادر می‌کند، به یک پروژه محدودند و دقیقاً یک‌بار هنگام ساخت به‌طور کامل نمایش داده می‌شوند.

HTTP
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] پایان می‌یابد. مصرف و تصمیم مسیریابی در آخرین چانک، پیش از پایان‌دهنده، می‌رسند.

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]

تصویر، 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
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 می‌پذیرند، نه ویدئو. برای ساخت ویدئو، بخش «ساخت ویدئو» را در ادامه ببینید.

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 را بفرستید (تابع‌هایی با JSON Schema آرگومان‌هایشان) و در صورت نیاز tool_choice و parallel_tool_calls را. مدل با tool_calls و finish_reason برابر tool_calls پاسخ می‌دهد؛ تابع را اجرا کنید، سپس پیام assistant را همراه یک پیام tool که نتیجه و tool_call_id را دارد برگردانید. در حالت پخش زنده، فراخوانی‌ها به‌صورت delta می‌آیند و index می‌گوید هر تکه از arguments مال کدام فراخوانی است. فقط ابزارهای تابعی منتقل می‌شوند؛ مدلی که ابزار ندارد رد می‌شود.

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 و خروجی ساختاریافته

مقدار response_format: {"type": "json_object"} یک شیء JSON می‌خواهد؛ {"type": "json_schema", "json_schema": {"name", "schema", "strict"}} پاسخی می‌خواهد که از اسکیمای شما پیروی کند، روی مدل‌هایی که 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
    }
  }
}

ساخت و ویرایش تصویر

یک مدل تصویری (در صفحه‌اش نوشته «تصویر می‌سازد») را با یک پرامپت صدا بزنید. تصویرها روی 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
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
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
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
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) و هزینه‌ای کسر نمی‌شود: کمی بعد دوباره بفرستید یا مدل دیگری انتخاب کنید.

JSON
{
  "error": {
    "type": "upstream_unavailable",
    "message": "All endpoints for this model are unavailable.",
    "request_id": "req_8Kd2Qm",
    "retryable": true,
    "attempts": 3
  }
}
نوعHTTPقابل تلاش مجدد
invalid_request400خیر
invalid_api_key401خیر
insufficient_credit402خیر
policy_violation403خیر
content_blocked400خیر
model_not_found404خیر
not_found404خیر
context_length_exceeded400خیر
rate_limit_exceeded429بله
budget_exceeded429خیر
internal_error500خیر
upstream_error502بله
upstream_unavailable503بله
upstream_timeout504بله