رفتن به محتوا
v1.1 · فعالREST · JSONUSD

مستندات API

کارهای ناهمگام، وب‌هوک‌های امضاشده، اندپوینت‌های سازگار با OpenAI. برای هر اجرا پرداخت می‌کنید و هزینه کارهای ناموفق برگردانده می‌شود.

URL پایهhttps://api.fcaai.ai/v1

شروع سریع

  1. ساخت کلیدحساب › کلیدهای توسعه‌دهنده. برای جدا نگه داشتن توسعه از محیط اصلی از کلید آزمایشی استفاده کنید؛ هزینه اجراها یکسان است: fcaai_test_ آن را در FCAAI_API_KEY بگذارید؛ SDKها و CLI آن را از همان‌جا می‌خوانند.
  2. نصب SDK یا CLITypeScript برای Node 18+‎، Deno، Bun و محیط‌های edge، Python 3.9+‎ یا ترمینال. curl نصب نمی‌خواهد. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. اولین تولید خود را اجرا کنیدفراخوانی بلافاصله 202 را همراه با شناسه کار و قیمتش برمی‌گرداند. با { wait: true }، SDK پس از تمام شدن کار پاسخ می‌دهد.
export FCAAI_API_KEY="fcaai_test_…"

# 1) queue a job → 202 { "id", "status": "queued", "price_usd", "eta_seconds" }
curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"fca/magic-pro","input":{"prompt":"glass villa on a pine ridge at blue hour","aspect_ratio":"16:9","resolution":"2k"}}'

# 2) long poll: holds up to 60 s, returns as soon as the job ends; repeat while queued/running
curl "https://api.fcaai.ai/v1/generations/$GEN_ID?wait=50" \
  -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "succeeded", "output": [{ "url": "https://…", "kind": "image", … }]

احراز هویت

کلید خود را در هر درخواست به‌صورت bearer token بفرستید.

  • کلیدهایی که با fcaai_live_ شروع می‌شوند برای محیط اصلی و کلیدهایی که با fcaai_test_ شروع می‌شوند برای توسعه هستند. هزینه هر دو یکسان است؛ کلیدهای آزمایشی فقط محیط‌ها را از هم جدا نگه می‌دارند.
  • کلید فقط یک بار، هنگام ساخت، نمایش داده می‌شود و ما فقط اثر انگشت آن را نگه می‌داریم. آن را در یک متغیر محیطی مثل FCAAI_API_KEY نگه دارید، هرگز در کدی که در مرورگر یا برنامه اجرا می‌شود.
  • کلید ناموجود، نادرست، باطل‌شده یا منقضی 401 برمی‌گرداند. کلیدی که دامنه درست را ندارد یا از IP خارج از فهرست مجازش استفاده شود، 403 برمی‌گرداند.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

نتیجه‌ها چطور برمی‌گردند

هر تولید یک کار است: queued ← running ← succeeded، failed یا canceled. هزینه کارهای ناموفق و لغوشده برگردانده می‌شود.

{
  "id": "cmvusmtm300234pbo7l6ecl3f",
  "object": "generation",
  "model": "fca/magic-pro",
  "status": "queued",
  "price_usd": 0.03,
  "currency": "USD",
  "eta_seconds": 14,
  "output": null
}

لغو یک تولید

تولیدی که در صف است قابل لغو است و مبلغ رزروشده‌اش آزاد می‌شود. وقتی شروع شد معمولاً نمی‌شود: پاسخ 409 already_started می‌گیرید و کار مثل همیشه تمام و هزینه‌اش کم می‌شود.

  • اول cancellable را روی تولید بخوانید: تا وقتی در صف است همیشه true است و پس از شروع معمولاً false.
  • لغو تولیدی که قبلاً تمام شده، آن را بدون تغییر برمی‌گرداند.
# can it still be cancelled?
curl https://api.fcaai.ai/v1/generations/$GEN_ID -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "queued", "cancellable": true, …

curl -X POST https://api.fcaai.ai/v1/generations/$GEN_ID/cancel -H "Authorization: Bearer $FCAAI_API_KEY"
# → 200: the generation, "status": "canceled"
# → 409 "already_started": it finishes and is charged as usual

مصرف و موجودی

GET /v1/account/usage تولیدها، خطاها و هزینه به دلار را به تفکیک روز و مدل برمی‌گرداند. اگر from و to را به‌صورت YYYY-MM-DD نفرستید، 30 روز گذشته را پوشش می‌دهد.

  • GET /v1/account/balance موجودی قابل استفاده شما را به دلار برمی‌گرداند.
# per day and model; the last 30 days unless you pass from and to
curl "https://api.fcaai.ai/v1/account/usage?from=2026-10-01&to=2026-10-31" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/account/balance -H "Authorization: Bearer $FCAAI_API_KEY"
گام‌به‌گام

راهنماها

دستورالعمل‌های قدم‌به‌قدم برای رایج‌ترین کارها. نمونه‌ها از SDKهای رسمی استفاده می‌کنند؛ زبانه curl درخواست HTTP ساده را نشان می‌دهد.

ویرایش تصویر با تصاویر مرجع

عکسی را که می‌خواهید ویرایش شود و تصاویر مرجع را در یک فهرست images بفرستید، سپس تغییر را توضیح دهید. به تصاویر با ترتیبشان اشاره کنید (تصویر 1، تصویر 2…).

  1. فایل‌های محلی را بارگذاری کنید یا از هر URL عمومی https استفاده کنید.
  2. تصویری را که باید ویرایش شود اول در images بگذارید؛ بقیه مرجع هستند.
  3. constraints.max_input_images را در جزئیات مدل بررسی کنید: نشان می‌دهد مدل چند تصویر می‌پذیرد.

شخصیت‌ها، محصولات و مکان‌های ذخیره‌شده در کتابخانه را می‌توانید با element_ids اضافه کنید (حداکثر 3)؛ تصاویر مرجعشان از سمت ما پیوست می‌شود.

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","input":{"prompt":"Put the armchair from image 2 next to the window. Keep the room, light and camera unchanged.","images":["https://example.com/room.jpg","https://example.com/armchair.jpg"],"resolution":"2k"}}'

# how many images this model takes
curl https://api.fcaai.ai/v1/models/google/nano-banana-pro -H "Authorization: Bearer $FCAAI_API_KEY"
# → "constraints": { "max_input_images": …, … }

تصویر به ویدیو با فریم شروع و پایان

مدل‌های ویدیو فریم اول را در image و، اگر پشتیبانی کنند، فریم آخر را در end_image می‌گیرند. کلیپ از یکی به دیگری حرکت می‌کند.

  1. مدل را بررسی کنید: constraints.features.end_frame باید true باشد و مدت باید با constraints.duration جور باشد.
  2. image، end_image، پرامپت و مدت را بفرستید. حرکت‌های دوربین همان متن ساده پرامپت هستند.
  3. ویدیو چند دقیقه طول می‌کشد: با timeout طولانی‌تر منتظر بمانید یا از وب‌هوک استفاده کنید.

مدل‌هایی که features.reference دارند حالت مرجع هم دارند: به‌جای فریم‌ها reference_images را بفرستید و در پرامپت آن‌ها را @Image1، @Image2 بنامید. این حالت با image یا end_image ترکیب نمی‌شود.

# price with an end frame
curl "https://api.fcaai.ai/v1/models/kling/3.0-pro?duration=5&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling/3.0-pro","input":{"prompt":"slow dolly in, morning light moves across the floor","image":"https://example.com/start.jpg","end_image":"https://example.com/end.jpg","duration":5}}'

افزایش وضوح تصویر

ابزارهای افزایش وضوح یک image و یک مقیاس در tier می‌گیرند. fca/upscale دو حالت دارد: Standard برای عکس‌ها (تا 16x) و Sharp برای رندرها، پلان‌ها و متن (تا 4x).

  1. قیمت را برای اندازه تصویر مبدأ بگیرید: ?tier=4x&source_width=…&source_height=….
  2. تصویر و مقیاس را بفرستید. "tier": "max" بزرگ‌ترین مقیاسی را که با تصویر جور است انتخاب می‌کند (خروجی تا 64 مگاپیکسل).
  3. اندازه جدید در width / height خروجی آمده است.

بهبوددهنده‌ها، نورپردازی دوباره، گسترش تصویر، حذف پس‌زمینه و افزایش وضوح ویدیو با GET /v1/models?type=upscale فهرست می‌شوند.

curl "https://api.fcaai.ai/v1/models/fca/upscale?tier=4x&source_width=1600&source_height=1000" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/upscale","input":{"image":"https://example.com/render.jpg","tier":"4x","extra":{"look":"sharp"}}}'

اجرای یک قالب

قالب‌ها دستورالعمل‌های آماده‌ای با چند ورودی نام‌دار هستند. پرامپت سمت ما می‌ماند: شما مقادیر را می‌فرستید و یک تولید معمولی پس می‌گیرید.

  1. قالب را بگیرید تا inputs (کلید، نوع، الزامی، گزینه‌ها) و pricing آن را ببینید.
  2. آن را با { "values": { key: value } } اجرا کنید. ورودی‌های تصویری یک URL https می‌گیرند.
  3. مثل هر کار دیگری منتظرش بمانید. مقدار نادرست پاسخ 400 invalid_values را همراه با fields برمی‌گرداند.

قالب‌های چندمرحله‌ای (package) یک اجرای قالب با چند مرحله شروع می‌کنند: از templates.runPackage / run_package استفاده کنید.

curl https://api.fcaai.ai/v1/templates -H "Authorization: Bearer $FCAAI_API_KEY"
curl https://api.fcaai.ai/v1/templates/$SLUG -H "Authorization: Bearer $FCAAI_API_KEY"     # inputs, pricing, options (models[].id → run "model")

curl https://api.fcaai.ai/v1/templates/$SLUG/run \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"values":{"photo":"https://example.com/room.jpg"}}'
# → 202: a generation (poll GET /v1/generations/{id}?wait=50)
#   multi-step templates return a template_run (GET /v1/templates/runs/{id})

اول قیمت و گزینه‌های مدل را بگیرید

یک فراخوانی رایگان هر چیزی را که مدل می‌پذیرد و قیمت دقیق تنظیمات شما را برمی‌گرداند. از همان منطق قیمت‌گذاری POST /v1/generations استفاده می‌کند، پس قیمت اعلام‌شده همان مبلغی است که می‌پردازید.

  1. GET /v1/models/{id} را با تنظیماتی که می‌فرستید فراخوانی کنید: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. قیمت را در estimate.price_usd بخوانید و پیش از اجرا availability را بررسی کنید.
  3. فرم خود را از روی options و constraints بسازید: نسبت‌های تصویر، وضوح‌ها، مدت، حداکثر خروجی، حداکثر تصویر ورودی و قابلیت‌ها.

مقداری که مدل اجازه نمی‌دهد در invalid_params برمی‌گردد، همراه با فیلد و مقادیر مجاز.

curl "https://api.fcaai.ai/v1/models/google/veo-3.1?duration=8&resolution=1080p&audio=1&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"
# → { "availability": "available",
#     "estimate": { "price_usd": …, "price_display": "$…", "currency": "USD" },
#     "options": { … }, "constraints": { … }, "input_schema": { … } }

curl "https://api.fcaai.ai/v1/models?type=video" -H "Authorization: Bearer $FCAAI_API_KEY"   # the whole catalog for your key

فایل‌هایتان را بارگذاری کنید

هر ورودی یک URL https است. URLهای عمومی همان‌طور کار می‌کنند؛ فایل‌های محلی را اول بارگذاری کنید و از url برگشتی استفاده کنید.

  1. تا 50 مگابایت: یک درخواست به POST /v1/uploads.
  2. تا 2 گیگابایت: یک نشست باز کنید، تکه‌های 8 مگابایتی را با هر ترتیبی (حتی موازی) بفرستید، سپس آن را کامل کنید.
  3. هنگام باز کردن نشست sha256 را بفرستید تا بارگذاری قطع‌شده ادامه پیدا کند یا فایلی که قبلاً ذخیره شده رد شود.

SDKها و CLI فایل را تکه می‌کنند، هر بار 3 تکه می‌فرستند و با شناسه نشست ادامه می‌دهند.

# ≤ 50 MB
curl https://api.fcaai.ai/v1/uploads -H "Authorization: Bearer $FCAAI_API_KEY" -F "[email protected]"
# → 201 { "id": "…", "object": "upload", "url": "https://…", "mime": "image/jpeg", "bytes": … }

# up to 2 GB: 1) start a session
curl https://api.fcaai.ai/v1/uploads/sessions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walkthrough.mp4","mime":"video/mp4","bytes":104857600}'
# 2) PUT each 8 MB chunk (any order, in parallel)
split -b 8388608 -d -a 4 walkthrough.mp4 part_
curl -X PUT https://api.fcaai.ai/v1/uploads/sessions/$SESSION/chunks/0 -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/octet-stream" --data-binary @part_0000
# 3) finish → { "upload": { "url": … } }
curl -X POST https://api.fcaai.ai/v1/uploads/sessions/$SESSION/complete -H "Authorization: Bearer $FCAAI_API_KEY"

دریافت نتیجه با وب‌هوک

به‌جای پرس‌وجوی مداوم، بگذارید وقتی کاری تمام شد سرورتان را صدا بزنیم. یک URL برای کل حساب ثبت کنید یا options.webhook_url را به یک درخواست اضافه کنید (رمز آن یک بار به‌صورت webhook_secret برمی‌گردد).

  1. با POST /v1/webhooks ثبت کنید: URL https شما و رویدادهایی که می‌خواهید. secret فقط یک بار نمایش داده می‌شود، پس ذخیره‌اش کنید.
  2. هر ارسال را بررسی کنید: X-FCAAI-Signature: t=…,v1=… یک HMAC-SHA256 از t + "." + rawBody با رمز شماست. از بدنه خام استفاده کنید و مهرهای زمانی قدیمی را رد کنید.
  3. سریع 2xx پاسخ دهید و کار را بعد انجام دهید. ارسال ناموفق در مجموع 5 بار تلاش می‌شود: بلافاصله، سپس پس از 30 ثانیه، 2 دقیقه، 10 دقیقه و 1 ساعت. همه تلاش‌ها در GET /v1/webhooks/{id}/deliveries ثبت می‌شوند.

یک رویداد ممکن است بیش از یک بار برسد؛ با id آن موارد تکراری را رد کنید.

رویدادها
generation.succeededgeneration.failedgeneration.canceledflow_run.succeededflow_run.failedflow_run.canceledtimeline.preview_readytimeline.donetimeline.failedapproval.requestedapproval.decided

فقط آدرس‌های https عمومی پذیرفته می‌شوند و آدرس در هر ارسال دوباره بررسی می‌شود.

curl https://api.fcaai.ai/v1/webhooks \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fcaai-hook","events":["generation.succeeded","generation.failed"]}'
# → 201 { "id": "…", "events": [ … ], "secret": "whsec_…" }   (secret shown only here)

# or one event for one job: add to POST /v1/generations
#   "options": { "webhook_url": "https://example.com/fcaai-hook" }
# → the 202 response carries "webhook_secret" (shown only there)

# delivery log: the latest 50 attempts
curl https://api.fcaai.ai/v1/webhooks/$WEBHOOK_ID/deliveries -H "Authorization: Bearer $FCAAI_API_KEY"

مدیریت خطاها و تنظیمات نادیده‌گرفته‌شده

خطاها به‌صورت JSON با یک error.code ثابت برمی‌گردند که می‌توانید بر اساسش تصمیم بگیرید. تنظیمی که اعمال نشود کار را ناموفق نمی‌کند: در ignored_fields فهرست می‌شود.

  1. وضعیت HTTP و error.code را بررسی کنید. وقتی مقداری نادرست است، allowed مقادیر معتبر را فهرست می‌کند.
  2. خطاهای 429 و 5xx را پس از Retry-After با همان Idempotency-Key دوباره امتحان کنید تا هیچ چیز دو بار حساب نشود. SDKها هر دو را برایتان انجام می‌دهند.
  3. ignored_fields را در پاسخ 202 بخوانید؛ هر مورد field · reason · message دارد.

هزینه کارهای ناموفق خودکار برگردانده می‌شود. اگر مسیر معمول یک مدل از کار افتاده باشد، کار خودبه‌خود به مسیر پشتیبان می‌رود؛ 503 model_unavailable یعنی الان هیچ مسیری آزاد نیست.

وضعیتکدهاچه باید کرد
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedیک فیلد جا افتاده یا برای این مدل مجاز نیست. درخواست را اصلاح کنید؛ ارسال دوباره بدون تغییر باز هم ناموفق می‌شود.
401invalid_api_keyapi_key_revokedapi_key_expiredکلید وجود ندارد، نادرست است، باطل شده یا منقضی شده است.
402insufficient_balancekey_spend_cap_reachedموجودی کافی نیست یا کلید به سقف ماهانه‌اش رسیده است. هزینه‌ای کم نشده است.
403insufficient_scopeip_not_allowedکلید دامنه لازم را ندارد (required_scope را ببینید) یا IP درخواست در فهرست مجاز آن نیست.
404model_not_foundچنین مدلی وجود ندارد یا برای کلید شما باز نیست.
429rate_limitedدرخواست‌ها بیش از حد زیاد است. به اندازه زمان Retry-After صبر کنید.
503model_unavailableمدل مشغول یا آفلاین است. کمی بعد دوباره امتحان کنید یا مدل دیگری انتخاب کنید.
دلیل‌ها در ignored_fields
unknown_field
فیلدی از این درخواست نیست؛ املای آن را بررسی کنید.
not_supported_by_model
فیلدی معتبر که این مدل نمی‌پذیرد.
nearest_supported
این نسبت تصویر ارائه نمی‌شود؛ نزدیک‌ترین نسبت استفاده می‌شود.
follows_input_image
هنگام ویرایش، این مدل اندازه یا نسبت تصویر ورودی را نگه می‌دارد.
unpriced_extra
یک تنظیم اضافه که مدل تعریف نکرده بود حذف شد.
import { Fcaai, FcaaiError } from '@fcaai/sdk'

type Ignored = { field: string; reason: string; message: string }
const fcaai = new Fcaai({ maxRetries: 2 }) // 429 / 5xx / network errors: retried with backoff, honoring Retry-After

try {
  const gen = await fcaai.generations.create({ model: 'google/veo-3.1', input: { prompt: 'waves at dusk, slow pan', duration: 6 } })
  const { ignored_fields = [] } = gen as unknown as { ignored_fields?: Ignored[] }
  for (const f of ignored_fields) console.warn(f.field + ' ignored (' + f.reason + '): ' + f.message)
} catch (e) {
  if (!(e instanceof FcaaiError)) throw e
  const allowed = (e.body as { error?: { allowed?: unknown[] } } | null)?.error?.allowed
  if (e.status === 400) console.error(e.code, e.message, allowed)   // fix the request; do not retry as is
  else if (e.status === 402) console.error('Top up, or raise the key cap:', e.message)
  else if (e.code === 'model_unavailable') console.error('Retry shortly or pick another model')
  else throw e
}

اندپوینت‌های سازگار با OpenAI

کدی که از کلاینت OpenAI استفاده می‌کند با تغییر دو چیز کار می‌کند: URL پایه و کلید. چت و تولید تصویر پشتیبانی می‌شوند.

  1. URL پایه را روی https://api.fcaai.ai/v1 بگذارید و کلید fcaai خود را به‌عنوان کلید API استفاده کنید.
  2. چت: POST /v1/chat/completions با مدل fca/chat. استریم، ابزارها و خروجی JSON مثل همیشه کار می‌کنند.
  3. تصویر: POST /v1/images/generations تا 90 ثانیه منتظر می‌ماند و data[].url را برمی‌گرداند. اگر کار بیشتر طول بکشد، 202 همراه با fcaai.generation_id می‌گیرید؛ با GET /v1/generations/{id} دنبالش کنید.

برای ویدیو، صدا، سه‌بعدی، افزایش وضوح و همه گزینه‌های مدل از POST /v1/generations استفاده کنید.

curl https://api.fcaai.ai/v1/chat/completions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/chat","messages":[{"role":"user","content":"Write a one-line caption for a walnut side table."}]}'

curl https://api.fcaai.ai/v1/images/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","prompt":"a paper plane on a wooden desk","size":"1536x1024"}'
# → { "created": …, "data": [{ "url": "https://…" }], "fcaai": { "generation_id": "…", "price_usd": … } }

فروش دوباره به مشتریان خودتان

حساب‌های نمایندگی می‌توانند برای هر مشتری یک زیرحساب باز کنند، کلیدهای مخصوص به آن بدهند و مصرف هر مشتری را با قیمت عمده دنبال کنند.

  1. از یک کلید مدیریتی با دامنه reseller:manage استفاده کنید. کلیدهای مشتری هرگز این دامنه را نمی‌گیرند.
  2. مشتری را با POST /v1/reseller/subtenants بسازید، سپس کلیدش را با POST /v1/reseller/subtenants/{id}/keys. کلید کامل فقط یک بار نمایش داده می‌شود.
  3. مصرف و حاشیه سود هر مشتری را با GET /v1/reseller/usage دنبال کنید. برای برچسب‌گذاری کاربران نهایی خودتان روی تولیدها، external_user_id را بفرستید.

کلیدهای بدون دامنه نمایندگی روی این اندپوینت‌ها 403 می‌گیرند.

curl https://api.fcaai.ai/v1/reseller/subtenants \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Acme Studio","plan":"pro","retail_markup":1.5}'

curl https://api.fcaai.ai/v1/reseller/subtenants/$CUSTOMER_ID/keys \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"production","mode":"live"}'

curl "https://api.fcaai.ai/v1/reseller/usage?from=2026-10-01" -H "Authorization: Bearer $FCAAI_RESELLER_KEY"
مرجع

چه چیزهایی می‌توانید بسازید

69 اندپوینت. هر کدام با نمونه‌های curl، TypeScript و Python در مرجع کامل آمده است.

GET/v1/style-kitsکیت‌های سبک
GET/v1/elementsالمان‌ها
POST/v1/video-editsویرایش ویدیو: کوتاه کردن، اتصال، تصاویر، متن و لوگو، موسیقی متن (ناهمگام، رایگان)
GET/v1/generationsفهرست تولیدها
POST/v1/generationsساخت تولید (ناهمگام)
GET/v1/generations/{id}دریافت تولید (long-poll با wait)
POST/v1/generations/{id}/cancelلغو (موجودی رزروشده آزاد می‌شود)

قیمت‌ها

دلار برای هر اجرا، از همان موجودی طرح شما. این‌ها قیمت‌های لحظه‌ای با تنظیمات پیش‌فرض‌اند؛ صفحه هر مدل همه قیمت‌ها را بر اساس وضوح و مدت فهرست می‌کند.

مدلکارAPI (دلار)
Nano Banana Proتصویر · تصویر · 2K$0.13
GPT Image 2.5 Flareتصویر · تصویر · 2K$0.055
FCA Magic Proتصویر · تصویر · 2K$0.03
Kling 3.0 Proویدیو · هر ثانیه · 1080p$0.11
FCA Magic V3ویدیو · هر ثانیه · 1080p$0.017
ElevenLabs v3صدا · کلیپ$0.024
استعلام قیمت رایگان استاعتبار اجرای ناموفق برمی‌گرددشارژ خودکار به‌طور پیش‌فرض خاموش استطرح نامحدود برای API وجود ندارد

کلیدها و محدودیت‌ها

هر کلید دامنه، نرخ و سقف هزینه خودش را دارد. هدرهای پاسخ نشان می‌دهند چقدر باقی مانده است.

120 / دقیقهنرخ پیش‌فرض درخواست برای هر کلید. X-RateLimit-*
2کارهای هم‌زمان برای هر کلید (قابل افزایش).
سقف ماهانهبه دلار؛ وقتی پر شود، درخواست‌ها 402 می‌گیرند key_spend_cap_reached
دامنهتصویر، ویدیو، صدا، سه‌بعدی، افزایش وضوح و LLM یکی‌یکی روشن می‌شوند.
فهرست IPهای مجازکلید را به آدرس‌های IP سرورهای خودتان محدود کنید.
Idempotency-Keyتلاش دوباره با همان کلید هرگز دو بار هزینه نمی‌گیرد.

SDKها و ابزارها

SDKهای رسمی TypeScript و Python و یک CLI. SDKها با کلیدهای idempotency با خیال راحت دوباره تلاش می‌کنند، منتظر نتیجه می‌مانند، فایل‌های بزرگ را تکه‌تکه بارگذاری می‌کنند و امضای وب‌هوک را بررسی می‌کنند.

TypeScriptnpmjs.com (در زبانه جدید باز می‌شود)Node 18+‎، Deno، Bun و محیط‌های edge
Pythonpypi.org (در زبانه جدید باز می‌شود)Python 3.9+‎، فقط کتابخانه استاندارد
CLInpmjs.com (در زبانه جدید باز می‌شود)همه مدل‌ها از ترمینال شما
MCPایجنت‌های هوش مصنوعی خود را به همین مدل‌ها و همین موجودی وصل کنید.
همه اندپوینت‌ها، فیلدها و کدهای خطا

مرجع تعاملی: درخواست‌ها را در مرورگر امتحان کنید و کد نمونه را کپی کنید.

مرجع کامل API(در زبانه جدید باز می‌شود)