کارهای غیرهم‌زمان
قرارداد اختصاصی و عمومی دانا برای عملیات طولانی؛ افزونهٔ HTTP، نه متد اختراعی SDK.
فهرست مستندات ۱۴ بخش
https://api.danaai.ai/v1/generations/generations/:idمسیرها نسبت به آدرس پایهٔ بالا هستند؛ احراز هویت با کلید دانا انجام می‌شود.
operation باید در فهرست عملیات همان مدل باشد: متن، استدلال، کد/محتوا، فایل، تصویر/ویرایش تصویر، ویدئو، گفتار، transcription، embedding یا moderation. Rerank و Realtime در adapterهای فعلی فعال نیستند.
پس از ثبت id را ذخیره کنید و GET همان کار را بگیرید. وضعیت‌ها queued، in_progress، completed و failed هستند. خروجی شامل متن عمومی، رسانهٔ متعلق به حساب یا دادهٔ ساختاریافتهٔ مجاز است؛ درصد پیشرفت ساختگی وجود ندارد.
idempotency_key با طول ۸ تا ۱۲۰، از حروف/اعداد و . - _ : ساخته می‌شود و به حساب، کلید API و بدنه متصل است. همان کلید و بدنه کار قبلی را برمی‌گرداند؛ تغییر بدنه 409 می‌دهد. درخواست هم‌زمان ممکن است request_in_progress بدهد.
بدون idempotency_key، هر POST کار جدید است. Responses و Chat این فیلد را قبول نمی‌کنند؛ retry خودکار را خاموش کنید. دریافت وضعیت هزینهٔ تولید جدید ندارد ولی از سقف نرخ درخواست استفاده می‌کند.
پارامترها و محدودیت‌ها
- model / operation / prompt
- شناسهٔ مدل، عملیات مجاز و متن درخواست.
- attachment_ids
- حداکثر ۱۴ شناسهٔ یکتای فایل آمادهٔ متعلق به حساب؛ URL دلخواه پذیرفته نیست.
- parameters
- متن: temperature/max_output_tokens/top_p/seed/responseFormat؛ تصویر: n یا count، size، quality، format/output_format و تنظیمات سازگار؛ گفتار: voice/speed/response_format؛ transcription: language/prompt/response_format؛ embedding: dimensions/encoding_format=float/inputs.
- video duration
- یکی از seconds، duration یا durationSeconds صریحاً لازم است؛ ۱ تا ۱۲۰ و سازگار با مدل. size، aspectRatio، resolution و seed اختیاری‌اند.
{ "model": "MODEL_ID_FROM_CATALOG", "operation": "image-generation", "prompt": "A minimal architectural photograph", "parameters": { "n": 1 }, "idempotency_key": "unique-image-request-0001"}GET /v1/generations/RETURNED_JOB_IDAuthorization: Bearer YOUR_DANA_API_KEYپاسخ و خطاها
id، status، model، operation، output[]، usage و در صورت شکست error. وضعیت queued، in_progress، completed یا failed است. idempotency با بدنه متفاوت: 409؛ کار ناموجود: 404.
- id / status
- شناسه کار و وضعیت
- output[]
- متن، فایل یا داده ساختاریافتهٔ عمومی
- usage.cost_toman
- هزینه نهایی به صورت رشته
- error
- null یا code و message خطا
احراز هویت: Authorization: Bearer DANA_API_KEY. خطاهای مشترک: 401 کلید نامعتبر، 403 دسترسی ناکافی، 429 محدودیت درخواست. خطاهای ورودی و خروجی این عملیات را در پارامترها و یادداشت‌های بالا بررسی کنید.
نمونه‌ها از پکیج رسمی openai یا HTTP استاندارد استفاده می‌کنند، نه «SDK جدید دانا». کپی‌کردن کد هیچ درخواست پولی ارسال نمی‌کند. کلید را فقط در سرور نگه دارید.