> ## 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

> HTTP पर Krea Agent सेशन प्रबंधित करें: अपनी API key से सेशन शुरू करें, किसी टर्न के पूरा होने की प्रतीक्षा करें, उसके परिणाम पढ़ें और फ़ॉलो-अप भेजें।

अपने स्वयं के एप्लिकेशन से Krea Agent को कोई कार्य देने के लिए Agent API का उपयोग करें। अनुरोध और रिस्पॉन्स camelCase JSON फ़ील्ड का उपयोग करते हैं। एजेंट बैकग्राउंड में काम करता है, जबकि आपका एप्लिकेशन उसकी प्रगति और परिणाम पढ़ता है।

| एंडपॉइंट | उद्देश्य |
| - | - |
| [`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>

## ऑथेंटिकेशन, एक्सेस और बिलिंग

`https://api.krea.ai` पर हर अनुरोध के साथ `Authorization: Bearer KREA_API_KEY` भेजें। पर्सनल, सर्विस और लेगेसी API keys मानक [पब्लिक API ऑथेंटिकेशन](/docs/hi/developers/api-keys-and-billing) का उपयोग करती हैं।

आप केवल वही सेशन पढ़ या जारी रख सकते हैं जो ऑथेंटिकेटेड वर्कस्पेस में ऑथेंटिकेटेड कॉलर के स्वामित्व में हों। सेशन ID जानने से एक्सेस नहीं मिलता। Krea फ़ाइल अटैचमेंट भी उस वर्कस्पेस में उस कॉलर के लिए एक्सेस योग्य होने चाहिए।

<Info>
  एजेंट टर्न वर्कस्पेस के compute unit बैलेंस का उपयोग करते हैं। वे API बैलेंस का उपयोग **नहीं** करते। Agent प्लान की पात्रताएँ और Free प्लान की संदेश सीमाएँ फिर भी लागू होती हैं। [Agent प्लान, एक्सेस और क्रेडिट](/docs/hi/user-guide/agent/plans-and-credits) देखें।
</Info>

हर रिस्पॉन्स में एक `url` शामिल होता है, जहाँ आप उपयुक्त अकाउंट और वर्कस्पेस एक्सेस के साथ Krea ऐप में सेशन खोल सकते हैं।

## सेशन शुरू करें और उसके परिणाम की प्रतीक्षा करें

पहले अपने एनवायरनमेंट में `KREA_API_KEY` सेट करें। `curl` और `jq` के साथ Bash, `requests` के साथ Python, या बिल्ट-इन `fetch` या Krea SDK के साथ Node.js चुनें।

<Steps>
  <Step title="पहला टर्न सबमिट करें">
    सेशन बनाने के लिए `sessionId` छोड़ दें। लौटाए गए `sessionId` और `runId` सहेजें। रिस्पॉन्स `status: "running"` के साथ तुरंत लौटता है।
  </Step>

  <Step title="इस टर्न की प्रतीक्षा करें">
    दोनों IDs को `wait-for-session` में पास करें। यदि `timedOut` का मान `true` है, तो उन्हीं IDs के साथ इसे फिर से कॉल करें। टाइमआउट से टर्न रद्द नहीं होता।
  </Step>

  <Step title="परिणाम पढ़ें">
    जब `finished` का मान `true` हो, तो `status` जाँचें। `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 के लिए, `pip install requests` से `requests` इंस्टॉल करें। Node.js के लिए, Node.js 22+ का उपयोग करें और उदाहरण को `example.mjs` के रूप में सहेजें। SDK उदाहरण के लिए `npm install @krea-ai/sdk` आवश्यक है और यह HTTP एंडपॉइंट्स को कॉल करने के लिए `requestRaw` का उपयोग करता है।

ये उदाहरण एक संदेश सबमिट करते हैं और अधिकतम पाँच मिनट तक प्रतीक्षा करते हैं। ये HTTP त्रुटियों और विफल या रद्द किए गए टर्न पर रुक जाते हैं। ये कभी भी अपने आप सेंड को दोबारा नहीं आज़माते। यदि कोई सेंड अनुरोध टाइम आउट हो जाता है, तो दोबारा सबमिट करने से पहले Krea में सेशन जाँचें; हो सकता है पहले अनुरोध ने कोई टर्न शुरू कर दिया हो।

जब प्रतीक्षा बजट समाप्त हो जाता है, तो टर्न बैकग्राउंड में जारी रहता है। बाद में प्रतीक्षा फिर से शुरू करने के लिए प्रिंट किए गए सेशन और रन IDs सहेजें।

`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')
```

एक सेशन एक समय में एक ही टर्न चलाता है। किसी टर्न के चलते समय दूसरा संदेश भेजने पर `code: "conflict"` के साथ `409` लौटता है।

## इनपुट और अटैचमेंट

`send-message` ये फ़ील्ड स्वीकार करता है। पूरे मॉडल enum और स्कीमा के लिए [रेफ़रेंस](/docs/api-reference/agent/send-agent-message) देखें।

| फ़ील्ड | व्यवहार |
| - | - |
| `sessionId` | वैकल्पिक UUID। नए सेशन के लिए छोड़ दें; अपने स्वामित्व वाले सेशन को जारी रखने के लिए शामिल करें। |
| `prompt` | स्ट्रिंग, अधिकतम 100,000 वर्ण। डिफ़ॉल्ट `""` है। एक गैर-रिक्त प्रॉम्प्ट या कम से कम एक अटैचमेंट आवश्यक है। |
| `attachments` | अधिकतम 20 अटैचमेंट। डिफ़ॉल्ट `[]` है। हर एक को `url` की आवश्यकता होती है और इसमें `name` और `contentType` शामिल हो सकते हैं। |
| `model` | वैकल्पिक Agent LLM ID। Auto के लिए छोड़ दें। पिन किया गया मॉडल वर्कस्पेस प्लान में शामिल होना चाहिए। |
| `effort` | वैकल्पिक: `fast`, `default`, `high` या `xhigh`। नए सेशन का डिफ़ॉल्ट `default` है; मौजूदा सेशन का effort बनाए रखने के लिए छोड़ दें। |
| `name` | वैकल्पिक सेशन नाम, केवल नए सेशन के लिए। ट्रिम किया हुआ, गैर-रिक्त और अधिकतम 120 वर्ण। |
| `desktopAppId` | किसी कनेक्टेड डेस्कटॉप ऐप की पहचान करने वाला वैकल्पिक UUID। यह टर्न उसी ऐप के भीतर चलाता है। ऐप ऑथेंटिकेटेड कॉलर और वर्कस्पेस के लिए उपलब्ध होना चाहिए। |

अटैचमेंट `url` एक एक्सेस योग्य HTTP(S) URL या एक अधिकृत Krea Files URI स्वीकार करता है, जैसे `file:550e8400-e29b-41d4-a716-446655440000`। वैकल्पिक `name` और `contentType` ट्रिम की हुई, गैर-रिक्त स्ट्रिंग्स हैं, अधिकतम 255 वर्ण। कॉलर के लोकल पाथ और OpenAI `file_` IDs समर्थित नहीं हैं। पहले वास्तविक फ़ाइल ट्रांसफ़र करें; प्रॉम्प्ट टेक्स्ट में ID देने से उसकी सामग्री ट्रांसफ़र नहीं होती।

एजेंट आपके एप्लिकेशन की बातचीत या अटैचमेंट इनहेरिट नहीं करता। ऐसी रेफ़रेंस फ़ाइलें अटैच करें जो अन्यथा एक्सेस योग्य नहीं हैं। प्रॉम्प्ट, मौजूदा Krea कॉन्टेक्स्ट या पिछली सेशन फ़ाइलों में पहले से मौजूद उपयोग योग्य URLs को दोहराने की आवश्यकता नहीं है।

## सेशन परिणाम

`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` देने पर, अंतिम टर्न का उस ID से मेल खाना भी आवश्यक है। |
| `text` | असिस्टेंट के नवीनतम संदेश का टेक्स्ट। |
| `media` | सेशन द्वारा बनाए गए मीडिया का ऐरे। क्रम महत्वपूर्ण नहीं है। |
| `error` | सेशन के लिए वैकल्पिक त्रुटि टेक्स्ट। |
| `url` | Krea ऐप में सेशन का लिंक। |
| `timedOut` | केवल प्रतीक्षा रिस्पॉन्स: यदि अनुरोधित टर्न पूरा होने से पहले समय-सीमा बीत गई तो `true`। |

हर `media` आइटम एक जनरेशन (`jobId` और वैकल्पिक `mediaKind`: `image`, `video`, `audio` या `3d`), रीहोस्ट किया गया मीडिया (`url`, वैकल्पिक `mimeType` के साथ), या एक Krea फ़ाइल (`uri`, `name`, `mimeType`) को दर्शा सकता है। जनरेशन विवरण `GET /jobs/{jobId}` के माध्यम से प्राप्त करें। आप किसी Krea फ़ाइल URI को अटैचमेंट के रूप में दोबारा उपयोग कर सकते हैं या उसकी फ़ाइलें देखने के लिए सेशन का `url` खोल सकते हैं। टर्न के चलते समय भी मीडिया दिखाई दे सकता है।

## त्रुटियाँ

एंडपॉइंट त्रुटियाँ `{ "error": "...", "code": "...", "allowedModels": ["..."] }` का उपयोग करती हैं। केवल `error` आवश्यक है। सबमिशन के बाद विफल होने वाला टर्न इसके बजाय एक सफल सेशन रिस्पॉन्स में `status: "failed"` के रूप में दिखाई देता है।

| HTTP स्टेटस | अर्थ |
| - | - |
| `400` | गलत तरीके से बना JSON बॉडी। |
| `401` | ऑथेंटिकेशन अनुपस्थित या अमान्य है। |
| `402` | वर्कस्पेस में अपर्याप्त compute unit बैलेंस (`compute_limit`) या Free प्लान की संदेश सीमा पूरी हो गई (`free_message_limit`)। |
| `403` | पिन किया गया मॉडल पात्रता में शामिल नहीं है (`model_not_entitled`); `allowedModels` अनुमत IDs सूचीबद्ध करता है। |
| `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.