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

# Text Generation

> Generate text using LLMs — GPT, Claude, Gemini, DeepSeek, Grok

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token: `Authorization: Bearer nb_YOUR_API_KEY`
</ParamField>

<ParamField body="model" type="string" required>
  Model slug. See [Text Models](/en/concepts/models#text-models) for all available slugs.

  Examples: `gpt-5`, `claude-sonnet-4.5`, `gemini-3-pro`, `deepseek-r1`
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects in OpenAI-compatible format.

  ```json theme={null}
  [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ]
  ```

  Supported roles: `system`, `user`, `assistant`
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Enable server-sent events streaming. See [Streaming Guide](/en/guides/streaming).
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
  Sampling temperature between `0.0` and `2.0`. Higher values make output more random.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens to generate. Defaults vary by model. Pass `null` to use model defaults.
</ParamField>

<ParamField body="system" type="string">
  Shorthand for adding a system message. Equivalent to adding `{ "role": "system", "content": "..." }` as the first message.
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://elumenta.ru/api/v2/generate \
    -H "Authorization: Bearer nb_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4.5",
      "system": "You are a helpful coding assistant.",
      "messages": [
        { "role": "user", "content": "Write a Python function to parse JSON safely" }
      ],
      "temperature": 0.5
    }'
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://elumenta.ru/api/v2/generate",
      headers={"Authorization": "Bearer nb_YOUR_API_KEY"},
      json={
          "model": "claude-sonnet-4.5",
          "system": "You are a helpful coding assistant.",
          "messages": [
              {"role": "user", "content": "Write a Python function to parse JSON safely"}
          ],
          "temperature": 0.5
      }
  )
  print(res.json()["content"])
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://elumenta.ru/api/v2/generate", {
    method: "POST",
    headers: {
      "Authorization": "Bearer nb_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "claude-sonnet-4.5",
      system: "You are a helpful coding assistant.",
      messages: [
        { role: "user", content: "Write a Python function to parse JSON safely" }
      ],
      temperature: 0.5
    })
  });

  const data = await res.json();
  console.log(data.content);
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique generation ID. Use this to retrieve results via [GET /generate/status](/en/api-reference/generations/status).
</ResponseField>

<ResponseField name="status" type="string">
  `completed` | `pending` | `failed`
</ResponseField>

<ResponseField name="model" type="string">
  The model slug used for this generation.
</ResponseField>

<ResponseField name="content" type="string">
  The generated text.
</ResponseField>

<ResponseField name="tokens_used" type="integer">
  Elumenta tokens consumed by this request.
</ResponseField>

<ResponseField name="balance_remaining" type="integer">
  Your token balance after this request.
</ResponseField>

<ResponseField name="usage" type="object">
  Raw provider token usage (for reference only, not billed):

  ```json theme={null}
  {
    "prompt_tokens": 142,
    "completion_tokens": 387,
    "total_tokens": 529
  }
  ```
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

## Response Example

````json theme={null}
{
  "id": "gen_01j9x2abc123",
  "status": "completed",
  "model": "claude-sonnet-4.5",
  "content": "Here's a safe JSON parsing function in Python:\n\n```python\nimport json\nfrom typing import Optional, Any\n\ndef parse_json_safe(text: str) -> Optional[Any]:\n    try:\n        return json.loads(text)\n    except (json.JSONDecodeError, TypeError):\n        return None\n```",
  "tokens_used": 3,
  "balance_remaining": 297,
  "usage": {
    "prompt_tokens": 142,
    "completion_tokens": 387,
    "total_tokens": 529
  },
  "created_at": "2026-03-08T12:00:00Z"
}
````

## Vision (Image Input)

Text models that support vision (`gpt-5`, `claude-sonnet-4.5`, `gemini-3-pro`) accept images in messages:

```json theme={null}
{
  "model": "gpt-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.jpg" }
        },
        {
          "type": "text",
          "text": "What's in this image?"
        }
      ]
    }
  ]
}
```

## Multi-turn Conversations

Pass the full conversation history in `messages`:

```json theme={null}
{
  "model": "gpt-5",
  "messages": [
    { "role": "user", "content": "My name is Ivan" },
    { "role": "assistant", "content": "Hello Ivan! How can I help you?" },
    { "role": "user", "content": "What's my name?" }
  ]
}
```

<Note>
  Elumenta does not store conversation state between requests. You must send the full history each time.
</Note>