API اپکس۲۴ با فرمت استاندارد سازگار است. کلید API خود را از پنل کاربری دریافت کنید.
آدرس پایه API (Base URL)
https://api.apx24.irاگر SDK شما مسیر را با /v1 تکراری بسازد (/v1/v1/...)، بهصورت خودکار نرمال میشود.
تمام درخواستها باید کلید API را در هدر Authorization بهصورت Bearer ارسال کنند:
Authorization: Bearer sk-apx-XXXXXXXXXXXXXXXXبرای دریافت لیست مدلهای موجود:
curl https://api.apx24.ir/v1/models \
-H "Authorization: Bearer sk-apx-..."curl https://api.apx24.ir/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "سلام!"}
],
"stream": false
}'برای پاسخ جریانی (Streaming)، "stream": true تنظیم کنید.
curl https://api.apx24.ir/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "سلام!"}
]
}'from openai import OpenAI
client = OpenAI(
api_key="sk-apx-...",
base_url="https://api.apx24.ir/v1"
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "سلام!"}]
)
print(response.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
apiKey: "sk-apx-...",
baseURL: "https://api.apx24.ir/v1",
});
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "سلام!" }],
});
console.log(response.choices[0].message.content);در تنظیمات Cursor به Settings → Models → Override OpenAI Base URL بروید:
https://api.apx24.ir/v1
API Key: sk-apx-...برای استفاده از Claude Code با اپکس۲۴:
export ANTHROPIC_BASE_URL=https://api.apx24.ir
export ANTHROPIC_API_KEY=sk-apx-...
claudecurl https://api.apx24.ir/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "text-embedding-3-small",
"input": "متن نمونه"
}'قیمت این مدلها به ازای هر تصویر است. پارامتر n تعداد تصویر (حداکثر ۱۰) را تعیین میکند و پاسخ شامل b64_json است.
curl https://api.apx24.ir/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "gemini-nano-banana-2.1",
"prompt": "a single indigo square on white background",
"n": 1
}'مدلهای تصویری موجود را با فیلتر قابلیت «تولید تصویر» در کاتالوگ ببینید.
برای ویرایش یا ترکیب عکسهای موجود (مدلهای GPT Image)، عکس را از مسیر جداگانهٔ POST /v1/images/edits با فرم multipart ارسال کنید — نه از chat/completions. فیلد image فایل عکس است (مدلهای GPT Image تا چند عکس مرجع با نام فیلد تکراری میپذیرند)، فیلد mask اختیاری است و سایر فیلدها (مانند size) عیناً پاس میشوند. سقف هر فایل ۲۵ مگابایت و حداکثر ۱۷ فایل در هر درخواست است.
curl https://api.apx24.ir/v1/images/edits \
-H "Authorization: Bearer sk-apx-..." \
-F "model=gpt-image-2.6-sunburst" \
-F "image=@cat.png" \
-F "prompt=a red hat on the cat"همان کار با Python SDK رسمی OpenAI:
from openai import OpenAI
client = OpenAI(api_key="sk-apx-...", base_url="https://api.apx24.ir/v1")
result = client.images.edit(
model="gpt-image-2.6-sunburst",
image=open("cat.png", "rb"),
prompt="a red hat on the cat",
)
# result.data[0].b64_jsonاگر عکس ورودی را بهصورت متنی میفرستید، مقدار data:image/...;base64,... در خود فیلد image پذیرفته میشود (پشتیبانی کلاینتهای غیر-SDK)؛ درخواست JSON به این مسیر پذیرفته نمیشود.
نکتهٔ فرمت خروجی: پاسخهای تصویری همیشه در فیلد b64_json میآیند ولی فرمت واقعی فایل همیشه PNG نیست — گاهی WebP یا JPEG برمیگردد. قبل از ذخیره، فرمت را از خود بایتها تشخیص دهید (سرآیند iVBOR = PNG، UklGR = WebP، /9j/ = JPEG)، نه از پسوند یا content-type حدسزدهشده.
ساخت ویدیو غیرهمزمان است: پاسخ اولیه یک شناسهٔ کار برمیگرداند و وضعیت را با همان مدل پیگیری میکنید. صورتحساب به ازای هر ثانیهٔ ویدیو است.
# ساخت
curl https://api.apx24.ir/v1/videos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "kling-3.0",
"prompt": "a slow pan over an indigo abstract surface",
"seconds": 6
}'
# پیگیری وضعیت
curl "https://api.apx24.ir/v1/videos/task_abc123?model=kling-3.0" \
-H "Authorization: Bearer sk-apx-..."
# دانلود فایل ویدیو (پس از completed)
curl "https://api.apx24.ir/v1/videos/task_abc123/content?model=kling-3.0" \
-H "Authorization: Bearer sk-apx-..." \
--output video.mp4وضعیتهای ممکن: queued، in_progress و completed. پیگیری وضعیت هزینهٔ جداگانه ندارد.
آدرس دانلود در پاسخها همیشه به خود درگاه اشاره میکند؛ فایل را با همان کلید اپکس۲۴ خودتان و از مسیر /v1/videos/<id>/content دریافت کنید (پشتیبانی از ادامهٔ دانلود با هدر Range). دانلود مجدد دوباره هزینهبر نیست.
برخی مدلها مقدار seconds را محدود میکنند (مثلاً خانوادهٔ MiniMax H3 فقط ۶ یا ۱۰ ثانیه). محدودیت هر مدل در پاسخ /v1/models زیر کلید apx.video_seconds_allowed اعلام میشود؛ درخواست با مقدار نامعتبر پیش از ارسال به مدل رد میشود.
ورودی تصویر (تصویر به ویدیو): برخی مدلهای ویدیویی یک تصویر فریم اول میپذیرند. قرارداد هر مدل در apx.video_image_input پاسخ /v1/models اعلام میشود: مقدار input_reference یعنی تصویر را در همان فیلد بفرستید، مقدار false یعنی آن مدل فقط متن میپذیرد (مثلاً MiniMax H3). مدل Kling 3.0 از تصویر فریم اول پشتیبانی میکند:
curl https://api.apx24.ir/v1/videos \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "kling-3.0",
"prompt": "gentle camera pan, cinematic motion",
"seconds": 5,
"input_reference": "data:image/png;base64,iVBORw0KGgo..."
}'تصویر باید بهصورت درونخطی (data:image/...;base64,...) ارسال شود؛ آدرسهای http برای تصویرِ منبع fetch نمیشوند و درخواست پیش از کسر هزینه با خطای image_remote_url_unsupported رد میشود. برای راحتی، فیلدهای image و image_url هم (بهشرط مقدار data-URL) بهصورت شفاف به input_reference نگاشت میشوند — این نگاشت با هدر پاسخ X-APX-Note اعلام میشود.
پاسخ یک فایل صوتی است. برخی مدلها به ازای هر درخواست و برخی به ازای هر کاراکتر محاسبه میشوند.
curl https://api.apx24.ir/v1/audio/speech \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-apx-..." \
-d '{
"model": "tts-1",
"input": "سلام، این متن به صدا تبدیل میشود.",
"voice": "alloy"
}' \
--output speech.mp3روی مدلهای DeepSeek و GLM کش بهصورت خودکار روی «پیشوند پایدار» مکالمه شما (بلوکهای ۶۴ توکنی) مینشیند؛ نیازی به ارسال cache_control نیست. برای اینکه کش معتبر بماند:
نتیجه در فیلد usage.cache_read_tokens قابل مشاهده است. در حالت stream این فیلد فقط در آخرین چانک میآید — گیتوی خودش stream_options.include_usage را تزریق میکند:
data: {"choices":[],"usage":{"prompt_tokens":4243,"prompt_tokens_details":{"cached_tokens":4096},"completion_tokens":4,"input_tokens":147,"cache_read_tokens":4096}}
data: [DONE]قیمتگذاری کش: توکنهای کشخوانده با نرخ ۰٫۱× قیمت ورودی و کشنوشته (مسیر Anthropic) با ۱٫۲۵× محاسبه میشوند.
شفافیت نرخ کش: در همهٔ پاسخهای درگاه (stream و non-stream) چهار هدر ASCII میآید: X-APX-Cache-Hit-Rate (نرخ ۲۴ ساعتهٔ کلید شما), X-APX-Cache-Warning (زیر ۳۰٪), X-APX-Model-Cache-Hit-Rate (نرخ سراسری مدلِ درخواستی) و X-APX-Model-Suggestion (مدل جایگزین سالم وقتی مدل شما کش نمیگیرد). در استریم، آخرین چانک usage یک بلوک افزودنی apx_cache دارد و در GET /v1/models هر مدل آمار کش و قیمت ورودی مؤثر را در بلوک apx میدهد.
اسکریپتها و هارنسها میتوانند قبل از انتخاب مدل، آمار زندهٔ کش همهٔ مدلها را بدون کلید از GET /v1/models/cache-stats?window=24h بگیرند (CORS باز؛ مدل «پیشنهادی» با کمترین قیمت مؤثرِ سالم فلگ میخورد).
نکتهٔ پیام system: پذیرش system-role روی همهٔ مدلها تضمینی نیست (بررسی زندهٔ ۲۰۲۶-۱۱-۰۱: نسخهٔ نامِ بدون پسوند deepseek-v4.1-flash محتوای system را حذف میکرد؛ مسیر آن به نسخهٔ سالم deepseek-v4.1-flash-1017 اصلاح شد). اگر روی مدلی دیدید مدل به دستورهای system عمل نمیکند، محتوای بلند و ثابت را در اولین پیام user بفرستید و system را خالی نگه دارید.
هر کلید API سقف RPM/TPM جداگانه دارد (پیشفرض ۶۰ درخواست و ۱۰۰٬۰۰۰ توکن قابلبیلینگ در دقیقه؛ توکنهای کشخوانده از سقف TPM کسر نمیشوند). در خطای 429 هدرهای Retry-After و X-RateLimit-Reset-Tokens را رعایت کنید و با backoff نمایی تلاش کنید — تلاش مکرر هر ۷ تا ۱۰ ثانیه فقط شمارنده را پر میکند. برای ایجنتهایی با کانتکست بزرگ، از پشتیبانی درخواست افزایش سقف بدهید.
| کد | معنی |
|---|---|
| 401 | کلید API نامعتبر یا ملغی شده |
| 402 | موجودی کافی نیست |
| 404 | مدل در دسترس نیست یا مسیریابی ندارد |
| 429 | محدودیت نرخ درخواست |
| 502 | خطا در اتصال به سرویسدهنده بالادستی |