# معرفی API

با API بنانا AI می‌توانید تولید و ویرایش عکس و ویدیو، گفتگو با مدل‌های زبانی، متن به گفتار، گفتار به متن و دوبله را به اپلیکیشن خود اضافه کنید؛ همان مدل‌های استودیو و مغز بنانا، با کلید API. عکس، ویدیو و دوبله ناهمگام (task) هستند؛ گفتگو، متن به گفتار و گفتار به متن همان لحظه پاسخ می‌دهند. هزینه فقط برای درخواست‌های موفق کم می‌شود.


## معرفی

API بنانا AI یک سرویس REST ساده است. از متن عکس یا ویدیو بسازید، عکس‌های موجود را ویرایش کنید، عکس را به ویدیو تبدیل کنید و نتیجه را با یک شناسه پیگیری کنید؛ یا با مدل‌های زبانی (GPT 6 Astra، Claude Haiku 5.5، Claude Opus 5.5، Grok 4.7، Gemini 3.5 Flash-Lite و …) گفتگو کنید. مدل‌های تصویری شامل Nano Banana، GPT Image، Seedream، Seedance، Grok Imagine، Gemini Omni، Kling و Veo 3.1 هستند. فهرست کامل: `GET /api/v1/models`. همه مسیرها نسخه‌بندی شده‌اند و با پیشوند `/api/v1` در دسترس هستند.

> برای ساخت کلید، شارژ کیف پول و دیدن مصرف، به https://api.bananaai.ir/console بروید.

## شروع سریع

هدر احراز هویت:

```bash
Authorization: Bearer ba_live_your_api_key
```

Base URL: `https://api.bananaai.ir`

## محدودیت نرخ درخواست

هر کلید تا 60 درخواست در دقیقه.

این محدودیت شامل polling وضعیت task هم می‌شود. در صورت عبور، HTTP `429` با کد `rate_limit_exceeded` و هدر `Retry-After` برمی‌گردد. برای 429 اعتباری کسر نمی‌شود.

## مراحل انجام کار (عکس و ویدیو)

1. درخواست تولید عکس یا ویدیو را بفرستید.
2. در پاسخ فیلد `id` را پارس کنید (نه `taskId` و نه `task_id`).
3. با همان مقدار، `GET /api/v1/tasks/:id` را هر ۳ تا ۵ ثانیه بررسی کنید تا به `completed` یا `failed` برسد.
4. اگر موفق باشد، URL عکس‌ها یا ویدیوها را در پاسخ بگیرید.

## گفتگو با مدل‌های زبانی

`POST /api/v1/chat/completions` با فرمت OpenAI Chat Completions سازگار است و پاسخ را همان لحظه (یا با `stream: true` تکه‌تکه) برمی‌گرداند؛ task و polling ندارد. هزینه بر اساس توکن مصرفی است (ورودی، ورودی کش‌شده و خروجی، نرخ هر ۱ میلیون توکن) و به طول پیام و پاسخ بستگی دارد. جزئیات: صفحه گفتگو با مدل‌های زبانی.

## Integration reliability

- شناسه task در JSON همیشه فیلد `id` است؛ `taskId` / `task_id` برنمی‌گردند.
- بعد از ساخت، همان `id` را در `GET /api/v1/tasks/:id` بگذارید و هر ۳ تا ۵ ثانیه poll کنید.
- اگر کلاینت timeout کرد، درخواست ساخت را کورکورانه retry نکنید؛ ممکن است task ساخته شده باشد. از هدر `Idempotency-Key` استفاده کنید، یا اگر `id` را دارید فقط وضعیت را poll کنید. جزئیات: صفحه احراز هویت.
- timeout کوتاه روی POST به‌معنی شکست قطعی نیست؛ معیار نهایی وضعیت task است. تولید ممکن است چند دقیقه طول بکشد.

> اعتبار فقط برای تولید موفق کسر می‌شود.

## صدا

- `POST /api/v1/audio/speech`: متن به گفتار با گویندگان فارسی؛ همگام، نشانی MP3 در `audio_url`.
- `POST /api/v1/audio/transcriptions`: گفتار به متن؛ همگام، متن در `text`.
- `POST /api/v1/audio/dubbing`: دوبله صوت/ویدیو به زبان دیگر؛ ناهمگام، مثل ویدیو با `GET /api/v1/tasks/:id` پیگیری کنید.