Skip to main content
استخدم Agent API لإسناد مهمة إلى Krea Agent من تطبيقك الخاص. تستخدم الطلبات والاستجابات حقول JSON بصيغة camelCase. يعمل الوكيل في الخلفية بينما يقرأ تطبيقك تقدّمه ونتائجه.
يعمل الوكيل في الخلفية. فهو لا يطرح أسئلة، وتتم الموافقة تلقائيًا على مطالبات التكلفة والأذونات. ضمّن جميع المتطلبات والقيود في موجّهك. راجع المهمة قبل إرسالها.

المصادقة والوصول والفوترة

أرسل Authorization: Bearer KREA_API_KEY مع كل طلب إلى https://api.krea.ai. تستخدم مفاتيح API الشخصية ومفاتيح الخدمة والمفاتيح القديمة مصادقة API العامة القياسية. لا يمكنك قراءة أو متابعة إلا الجلسات التي يملكها المستدعي المُصادَق عليه في مساحة العمل المُصادَق عليها. معرفة معرّف الجلسة لا تمنح حق الوصول. ويجب أيضًا أن تكون مرفقات ملفات Krea متاحة لذلك المستدعي في مساحة العمل تلك.
تستخدم دورات الوكيل رصيد وحدات الحوسبة في مساحة العمل. وهي لا تستخدم رصيد API. وتظل استحقاقات خطة الوكيل وحدود الرسائل في الخطة المجانية سارية. راجع خطط الوكيل والوصول والأرصدة.
تتضمن كل استجابة url يمكنك من خلاله فتح الجلسة في تطبيق Krea باستخدام الحساب وصلاحيات الوصول إلى مساحة العمل المناسبة.

بدء جلسة وانتظار نتيجتها

اضبط KREA_API_KEY في بيئتك أولًا. اختر Bash مع curl وjq، أو Python مع requests، أو Node.js مع fetch المدمج أو Krea SDK.
1

أرسل الدورة الأولى

احذف sessionId لإنشاء جلسة. احفظ قيمتي sessionId وrunId المُعادتين. تعود الاستجابة فورًا مع status: "running".
2

انتظر هذه الدورة

مرّر المعرّفين كليهما إلى wait-for-session. إذا كانت قيمة timedOut هي true، فاستدعِه مرة أخرى بالمعرّفين نفسيهما. انتهاء المهلة لا يُلغي الدورة.
3

اقرأ النتيجة

تحقّق من status عندما تكون قيمة finished هي true. افحص text وmedia وأي error، أو افتح url المُعاد.
بالنسبة إلى Python، ثبّت requests باستخدام pip install requests. بالنسبة إلى Node.js، استخدم Node.js 22 أو أحدث واحفظ المثال باسم example.mjs. يتطلب مثال SDK تنفيذ npm install @krea-ai/sdk ويستخدم requestRaw لاستدعاء نقاط نهاية HTTP. ترسل هذه الأمثلة رسالة واحدة وتنتظر حتى خمس دقائق. وتتوقف عند أخطاء HTTP وعند الدورات الفاشلة أو الملغاة. ولا تعيد محاولة الإرسال تلقائيًا أبدًا. إذا انتهت مهلة طلب إرسال، فتحقّق من الجلسة في Krea قبل الإرسال مرة أخرى؛ فقد يكون الطلب الأول قد بدأ دورة بالفعل. عندما تنتهي ميزانية الانتظار، تستمر الدورة في الخلفية. احفظ معرّفي الجلسة والتشغيل المطبوعين لاستئناف الانتظار لاحقًا. timeoutSeconds عدد صحيح من 1 إلى 300 وقيمته الافتراضية 60. اجعل مهلة عميل HTTP أطول من مدة الانتظار المطلوبة. مرّر دائمًا أحدث runId عند الانتظار بعد الإرسال، حتى لا تُفهم الحالة النهائية لدورة سابقة على أنها حالة الدورة الجديدة.

القراءة دون انتظار

استخدم GET /agent/session/{sessionId} لالتقاط لقطة من الجلسة الحالية:
cURL

متابعة الجلسة

بعد انتهاء الدورة، أرسل رسالة أخرى مع sessionId الخاص بها:
cURL
تُشغّل الجلسة دورة واحدة في كل مرة. يؤدي إرسال رسالة أخرى أثناء تشغيل دورة إلى إرجاع 409 مع code: "conflict".

المدخلات والمرفقات

يقبل send-message الحقول التالية. راجع المرجع للاطلاع على قائمة النماذج الكاملة والمخططات. يقبل url الخاص بالمرفق عنوان HTTP(S) يمكن الوصول إليه أو URI مصرّحًا به من Krea Files مثل file:550e8400-e29b-41d4-a716-446655440000. الحقلان الاختياريان name وcontentType سلسلتان نصيتان غير فارغتين تُزال منهما المسافات الطرفية، بحد أقصى 255 حرفًا. المسارات المحلية لدى المستدعي ومعرّفات OpenAI ‏file_ غير مدعومة. انقل الملف الفعلي أولًا؛ فوجود معرّف في نص الموجّه لا ينقل محتوياته. لا يرث الوكيل محادثة تطبيقك أو مرفقاته. أرفق الملفات المرجعية التي لا يمكن الوصول إليها بطريقة أخرى. لا تحتاج إلى تكرار عناوين URL القابلة للاستخدام الموجودة في الموجّه أو في سياق Krea الحالي أو في ملفات الجلسة السابقة.

نتائج الجلسة

يُعيد send-message القيم sessionId وthreadId وrunId وstatus (دائمًا "running") وurl. يُعيد كلٌّ من GET /agent/session/{sessionId} وwait-for-session عرض الجلسة التالي. ويضيف wait-for-session وحده الحقل الإلزامي timedOut. يمكن أن يمثّل كل عنصر في media عملية إنشاء (jobId مع mediaKind اختياري: image أو video أو audio أو 3d)، أو وسائط مُعاد استضافتها (url، مع mimeType اختياري)، أو ملف Krea ‏(uri وname وmimeType). اجلب تفاصيل عملية الإنشاء عبر GET /jobs/{jobId}. يمكنك إعادة استخدام URI ملف Krea كمرفق أو فتح url الخاص بالجلسة لعرض ملفاتها. قد تظهر الوسائط بينما لا تزال الدورة قيد التشغيل.

الأخطاء

تستخدم أخطاء نقاط النهاية الصيغة { "error": "...", "code": "...", "allowedModels": ["..."] }. الحقل error وحده إلزامي. أما الدورة التي تفشل بعد إرسالها فتظهر بدلًا من ذلك على شكل status: "failed" ضمن استجابة جلسة ناجحة.