> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> أدِر جلسات Krea Agent عبر HTTP: ابدأ جلسة، وانتظر انتهاء دورة، واقرأ نتائجها، وأرسل رسائل متابعة باستخدام مفتاح API الخاص بك.

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

| نقطة النهاية | الغرض |
| - | - |
| [`POST /agent/send-message`](/docs/api-reference/agent/send-agent-message) | بدء جلسة أو إرسال دورة متابعة. |
| [`GET /agent/session/{sessionId}`](/docs/api-reference/agent/get-agent-session) | قراءة الجلسة الحالية دون انتظار. |
| [`POST /agent/wait-for-session`](/docs/api-reference/agent/wait-for-agent-session) | انتظار انتهاء دورة، حتى مهلة زمنية محددة. |

<Warning>
  يعمل الوكيل في الخلفية. فهو لا يطرح أسئلة، وتتم الموافقة تلقائيًا على مطالبات التكلفة والأذونات. ضمّن جميع المتطلبات والقيود في موجّهك. راجع المهمة قبل إرسالها.
</Warning>

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

أرسل `Authorization: Bearer KREA_API_KEY` مع كل طلب إلى `https://api.krea.ai`. تستخدم مفاتيح API الشخصية ومفاتيح الخدمة والمفاتيح القديمة [مصادقة API العامة](/docs/ar/developers/api-keys-and-billing) القياسية.

لا يمكنك قراءة أو متابعة إلا الجلسات التي يملكها المستدعي المُصادَق عليه في مساحة العمل المُصادَق عليها. معرفة معرّف الجلسة لا تمنح حق الوصول. ويجب أيضًا أن تكون مرفقات ملفات Krea متاحة لذلك المستدعي في مساحة العمل تلك.

<Info>
  تستخدم دورات الوكيل رصيد وحدات الحوسبة في مساحة العمل. وهي **لا** تستخدم رصيد API. وتظل استحقاقات خطة الوكيل وحدود الرسائل في الخطة المجانية سارية. راجع [خطط الوكيل والوصول والأرصدة](/docs/ar/user-guide/agent/plans-and-credits).
</Info>

تتضمن كل استجابة `url` يمكنك من خلاله فتح الجلسة في تطبيق Krea باستخدام الحساب وصلاحيات الوصول إلى مساحة العمل المناسبة.

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

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

<Steps>
  <Step title="أرسل الدورة الأولى">
    احذف `sessionId` لإنشاء جلسة. احفظ قيمتي `sessionId` و`runId` المُعادتين. تعود الاستجابة فورًا مع `status: "running"`.
  </Step>

  <Step title="انتظر هذه الدورة">
    مرّر المعرّفين كليهما إلى `wait-for-session`. إذا كانت قيمة `timedOut` هي `true`، فاستدعِه مرة أخرى بالمعرّفين نفسيهما. انتهاء المهلة لا يُلغي الدورة.
  </Step>

  <Step title="اقرأ النتيجة">
    تحقّق من `status` عندما تكون قيمة `finished` هي `true`. افحص `text` و`media` وأي `error`، أو افتح `url` المُعاد.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  set -euo pipefail
  : "${KREA_API_KEY:?Set your Krea API key}"

  START=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/agent/send-message \
    -H "Authorization: Bearer $KREA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      "name": "Coffee mug campaign"
    }')

  SESSION_ID=$(printf '%s' "$START" | jq -er '.sessionId')
  RUN_ID=$(printf '%s' "$START" | jq -er '.runId')
  printf '%s' "$START" | jq -r '.url'

  DEADLINE=$((SECONDS + 300))

  while (( SECONDS < DEADLINE - 10 )); do
    WAIT_SECONDS=$((DEADLINE - SECONDS - 10))
    if (( WAIT_SECONDS > 60 )); then WAIT_SECONDS=60; fi
    WAIT_BODY=$(jq -n --arg sessionId "$SESSION_ID" --arg runId "$RUN_ID" \
      --argjson timeoutSeconds "$WAIT_SECONDS" \
      '{sessionId: $sessionId, runId: $runId, timeoutSeconds: $timeoutSeconds}')
    RESULT=$(curl --fail-with-body --silent --show-error --max-time "$((WAIT_SECONDS + 10))" \
      https://api.krea.ai/agent/wait-for-session \
      -H "Authorization: Bearer $KREA_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$WAIT_BODY")
    printf '%s' "$RESULT" | jq '{status, finished, timedOut, text, media, error, url}'
    if printf '%s' "$RESULT" | jq -e '.finished' > /dev/null; then
      if printf '%s' "$RESULT" | jq -e '.status == "completed"' > /dev/null; then
        exit 0
      fi
      printf '%s' "$RESULT" | jq -r '"Turn ended: \(.status). \(.error // "No error details")"' >&2
      exit 1
    fi
  done

  printf 'Wait budget exhausted; the turn continues. Resume waiting with sessionId=%s runId=%s\n' \
    "$SESSION_ID" "$RUN_ID" >&2
  exit 1
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import json
  import os
  import time
  import requests

  api = "https://api.krea.ai"
  headers = {"Authorization": f"Bearer {os.environ['KREA_API_KEY']}"}

  response = requests.post(
      f"{api}/agent/send-message",
      headers=headers,
      json={
          "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
          "name": "Coffee mug campaign",
      },
      timeout=60,
  )
  response.raise_for_status()
  start = response.json()
  session_id, run_id = start["sessionId"], start["runId"]
  print(start["url"])

  deadline = time.monotonic() + 300
  while True:
      wait_seconds = min(60, int(deadline - time.monotonic()) - 10)
      if wait_seconds < 1:
          raise TimeoutError(
              "Wait budget exhausted; the turn continues. Resume waiting with "
              f"sessionId={session_id} runId={run_id}"
          )
      response = requests.post(
          f"{api}/agent/wait-for-session",
          headers=headers,
          json={
              "sessionId": session_id,
              "runId": run_id,
              "timeoutSeconds": wait_seconds,
          },
          timeout=wait_seconds + 10,
      )
      response.raise_for_status()
      result = response.json()
      print(json.dumps(result, indent=2))
      if result["finished"]:
          if result["status"] != "completed":
              raise RuntimeError(
                  f"Turn ended: {result['status']}. {result.get('error', 'No error details')}"
              )
          break
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const api = "https://api.krea.ai";

  async function post(path, body, timeoutMs) {
    const response = await fetch(`${api}${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }
    return response.json();
  }

  const start = await post("/agent/send-message", {
    prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
    name: "Coffee mug campaign",
  }, 60_000);
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 10);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await post("/agent/wait-for-session", {
      sessionId,
      runId,
      timeoutSeconds,
    }, (timeoutSeconds + 10) * 1000);
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```

  ```javascript Node.js (SDK) theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";
  import { Krea } from "@krea-ai/sdk";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const krea = new Krea({ apiKey: token });

  const start = await krea.requestRaw("/agent/send-message", {
    method: "POST",
    retry: false,
    signal: AbortSignal.timeout(60_000),
    body: {
      prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      name: "Coffee mug campaign",
    },
  });
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 15);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await krea.requestRaw("/agent/wait-for-session", {
      method: "POST",
      retry: false,
      signal: AbortSignal.timeout((timeoutSeconds + 15) * 1000),
      body: { sessionId, runId, timeoutSeconds },
    });
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```
</CodeGroup>

بالنسبة إلى 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}` لالتقاط لقطة من الجلسة الحالية:

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
curl --fail-with-body --silent --show-error \
  "https://api.krea.ai/agent/session/$SESSION_ID" \
  -H "Authorization: Bearer $KREA_API_KEY"
```

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

بعد انتهاء الدورة، أرسل رسالة أخرى مع `sessionId` الخاص بها:

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
FOLLOW_UP=$(curl --fail-with-body --silent --show-error \
  https://api.krea.ai/agent/send-message \
  -H "Authorization: Bearer $KREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg sessionId "$SESSION_ID" \
    '{sessionId: $sessionId, prompt: "Make a landscape variation of the first image."}')")

# Use this new runId in the next wait-for-session request.
RUN_ID=$(printf '%s' "$FOLLOW_UP" | jq -er '.runId')
```

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

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

يقبل `send-message` الحقول التالية. راجع [المرجع](/docs/api-reference/agent/send-agent-message) للاطلاع على قائمة النماذج الكاملة والمخططات.

| الحقل | السلوك |
| - | - |
| `sessionId` | UUID اختياري. احذفه لإنشاء جلسة جديدة؛ وضمّنه لمتابعة جلسة تملكها. |
| `prompt` | سلسلة نصية تصل إلى 100,000 حرف. القيمة الافتراضية `""`. يلزم موجّه غير فارغ أو مرفق واحد على الأقل. |
| `attachments` | ما يصل إلى 20 مرفقًا. القيمة الافتراضية `[]`. يحتاج كل مرفق إلى `url` ويمكن أن يتضمن `name` و`contentType`. |
| `model` | معرّف LLM اختياري للوكيل. احذفه لاستخدام الوضع التلقائي. يجب أن يكون النموذج المثبّت مضمّنًا في خطة مساحة العمل. |
| `effort` | اختياري: `fast` أو `default` أو `high` أو `xhigh`. القيمة الافتراضية للجلسات الجديدة هي `default`؛ احذفه للإبقاء على مستوى الجهد الحالي للجلسة. |
| `name` | اسم اختياري للجلسة، للجلسات الجديدة فقط. تُزال منه المسافات الطرفية، ويجب ألا يكون فارغًا، وبحد أقصى 120 حرفًا. |
| `desktopAppId` | UUID اختياري يحدد تطبيق سطح مكتب متصلًا. يُشغّل هذه الدورة داخل ذلك التطبيق. يجب أن يكون التطبيق متاحًا للمستدعي المُصادَق عليه ومساحة العمل. |

يقبل `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`.

| الحقل | المعنى |
| - | - |
| `sessionId`, `threadId` | معرّفا الجلسة والسلسلة الجذرية. |
| `runId` | معرّف الدورة الحالية، عند توفره. |
| `status` | `not_started` أو `running` أو `completed` أو `failed` أو `cancelled`. |
| `finished` | `true` للدورة النهائية. عند تمرير `runId` إلى طلب انتظار، يجب أن تطابق الدورة النهائية ذلك المعرّف أيضًا. |
| `text` | نص أحدث رسالة من المساعد. |
| `media` | مصفوفة بالوسائط التي أنتجتها الجلسة. الترتيب غير مهم. |
| `error` | نص خطأ اختياري للجلسة. |
| `url` | رابط إلى الجلسة في تطبيق Krea. |
| `timedOut` | لاستجابات الانتظار فقط: `true` إذا انقضت المهلة قبل انتهاء الدورة المطلوبة. |

يمكن أن يمثّل كل عنصر في `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"` ضمن استجابة جلسة ناجحة.

| حالة HTTP | المعنى |
| - | - |
| `400` | جسم JSON غير صالح البنية. |
| `401` | المصادقة مفقودة أو غير صالحة. |
| `402` | رصيد وحدات الحوسبة في مساحة العمل غير كافٍ (`compute_limit`) أو تم بلوغ حد الرسائل في الخطة المجانية (`free_message_limit`). |
| `403` | النموذج المثبّت غير مشمول في الاستحقاقات (`model_not_entitled`)؛ يسرد `allowedModels` المعرّفات المسموح بها. |
| `404` | الجلسة مفقودة أو يتعذّر الوصول إليها (`not_found`)، أو مرفق ملف Krea مفقود أو يتعذّر الوصول إليه (`attachment_not_found`). |
| `409` | توجد دورة قيد التنفيذ بالفعل (`conflict`). |
| `422` | مدخلات غير صالحة، أو أن تطبيق سطح المكتب المحدد غير متاح. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.