# ساخت و استفاده از کلید API

برای استفاده از API، هر درخواست باید همراه با یک کلید API معتبر ارسال شود.


## هدر Authorization

```bash
Authorization: Bearer ba_live_your_api_key
```

## ساختار کلید

کلیدهای API با `ba_live_` شروع می‌شوند. کلید کامل فقط همان لحظه ساخت نمایش داده می‌شود، پس آن را در جای امن نگه دارید.

> احتیاط: کلید API را داخل کد frontend، مخزن عمومی یا لاگ‌های برنامه قرار ندهید. این کلید باید فقط در سرور یا محیط امن نگهداری شود.

## Idempotency-Key (اختیاری)

برای endpointهای ساخت (عکس/ویدیو) می‌توانید هدر `Idempotency-Key` بفرستید تا اگر پاسخ را نگرفتید و دوباره همان درخواست را زدید، task دوم ساخته نشود و همان `id` قبلی برگردد.

```bash
curl -X POST "https://api.bananaai.ir/api/v1/videos/image-to-video" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Idempotency-Key: order-42-video-1" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"...","image_urls":["https://example.com/a.jpg"]}'
```

قوانین:

- هدر اختیاری است؛ بدون آن رفتار API مثل قبل است.
- مقدار باید ۱ تا ۲۵۶ کاراکتر ASCII قابل چاپ باشد (بدون فاصله).
- برای هر عملیات منطقی یکتا باشد (مثلاً UUID یا شناسه سفارش شما).
- همان کلید + همان بدنه، در صورت موفقیت تا ۲۴ ساعت همان پاسخ را برمی‌گرداند (هدر `Idempotent-Replayed: true`).
- همان کلید با بدنهٔ متفاوت: HTTP `422` با کد `idempotency_key_reused`.
- اگر درخواست اول هنوز در حال اجراست: HTTP `409` با کد `idempotency_key_in_progress` و هدر `Retry-After`.

روی این مسیرها پشتیبانی می‌شود: `/api/v1/images/generations`، `/api/v1/images/edits`، `/api/v1/videos/generations`، `/api/v1/videos/image-to-video`، `/api/v1/audio/speech`، `/api/v1/audio/transcriptions`، `/api/v1/audio/dubbing` و `/api/v1/chat/completions` (فقط بدون `stream`).

## نکات امنیتی

- اگر کلیدی را لغو کنید، همان لحظه غیرفعال می‌شود.
- هر کلید به حساب کاربری شما وصل است و از اعتبار همان حساب استفاده می‌کند.
- بهتر است برای محیط توسعه و محیط اصلی، کلیدهای جداگانه بسازید.