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

# Chat Completions

> Create a chat completion

## Create Chat Completion

`POST /v1/chat/completions`

### Request Body

<ParamField body="model" type="string" required>
  Model to use for completion (e.g., `gpt-4o`, `gpt-5.1`, `claude-sonnet-4-6`, `deepseek-r1`). Append `:reasoning-exclude` to disable reasoning output for a single request.
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects forming the conversation.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens to generate. Reasoning tokens are billed as output tokens and counted against this limit.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between 0 and 2.
</ParamField>

<ParamField body="stream" type="boolean">
  Enable streaming responses (SSE).
</ParamField>

<ParamField body="reasoning_effort" type="string">
  Controls reasoning depth on supported models. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. Silently ignored for models that don't support reasoning\_effort.
</ParamField>

<ParamField body="reasoning" type="object">
  Reasoning configuration object. Supports:

  * `reasoning.effort` — same enum as `reasoning_effort`.
  * `reasoning.exclude` (boolean) — strip reasoning from the response entirely.
  * `reasoning.delta_field` — `"reasoning"` or `"reasoning_content"`; overrides the streaming/non-streaming field name regardless of which endpoint variant was hit.
</ParamField>

<ParamField body="reasoning_delta_field" type="string">
  Shorthand for `reasoning.delta_field`. Accepts `"reasoning"` or `"reasoning_content"`.
</ParamField>

<ParamField body="reasoning_content_compat" type="boolean">
  Shorthand: set to `true` to force the legacy `reasoning_content` field, equivalent to `reasoning.delta_field = "reasoning_content"`.
</ParamField>

## Endpoint Variants (Reasoning Output)

Some models emit a separate reasoning / thinking stream in addition to the final answer. Three base paths control how that stream is surfaced — **all of them accept the same request shape and model names**.

| Base path                           | Behavior                                                                                                    | Use when                                                                       |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `POST /v1/chat/completions`         | Reasoning and answer are returned as **separate fields** (`reasoning` + `content`). Default.                | Most OpenAI-compatible clients.                                                |
| `POST /v1legacy/chat/completions`   | Same as `/v1/`, but reasoning uses the legacy field name **`reasoning_content`**.                           | Clients that only parse `reasoning_content` (e.g. older DeepSeek SDKs).        |
| `POST /v1thinking/chat/completions` | Reasoning and answer are **merged into the normal `content` stream**, wrapped in `<think>...</think>` tags. | Clients that ignore reasoning fields but should still display thoughts inline. |

Per-request overrides (`reasoning.delta_field`, `reasoning_delta_field`, `reasoning_content_compat`) take precedence over the endpoint default. If a model does not emit reasoning, these fields are simply absent from the response.

### Streaming output shape

When reasoning is delivered as a separate field, deltas are interleaved — reasoning chunks come first, followed by content chunks:

```text theme={null}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"reasoning":"Let me think..."},"finish_reason":null}], ...}

data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":"The answer is 4."},"finish_reason":null}], ...}

data: [DONE]
```

Against `/v1legacy/chat/completions` the same deltas use `delta.reasoning_content` instead of `delta.reasoning`.

Against `/v1thinking/chat/completions` everything appears in `delta.content`:

```text theme={null}
data: {"choices":[{"delta":{"content":"<think>Let me think...</think>The answer is 4."}}]}
```

### Non-streaming output shape

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The answer is 4.",
      "reasoning": "Let me think..."
    },
    "finish_reason": "stop"
  }],
  "usage": { "...": "..." }
}
```

`reasoning` becomes `reasoning_content` on `/v1legacy/`. On `/v1thinking/`, the reasoning stays embedded inside `content` (`"<think>...</think>The answer..."`) and no separate field is emitted.

## Disabling Reasoning Output

Reasoning can be hidden in three equivalent ways — the model still pays the cost for reasoning compute, but the tokens are stripped from the response:

1. Request body: `{ "reasoning": { "exclude": true } }`
2. Model suffix: `"model": "deepseek-r1:reasoning-exclude"`
3. Request body: `{ "reasoning_effort": "none" }` *(only honored on OpenAI-shaped models — safely ignored elsewhere for API parity).*

When excluded, neither the `reasoning` field nor `<think>` tags appear in the response, regardless of which endpoint variant was hit.

### Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  # Default: reasoning + content in separate fields
  response = requests.post(
      'https://api.electronhub.ai/v1/chat/completions',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'model': 'deepseek-r1',
          'messages': [{'role': 'user', 'content': "What's 2 + 2?"}],
          'reasoning_effort': 'medium'
      }
  )
  data = response.json()
  print(data['choices'][0]['message']['reasoning'])  # thinking text
  print(data['choices'][0]['message']['content'])    # answer
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.electronhub.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ELECTRONHUB_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'deepseek-r1',
      messages: [{ role: 'user', content: "What's 2 + 2?" }],
      reasoning_effort: 'medium'
    })
  });
  const data = await res.json();
  console.log(data.choices[0].message.reasoning);
  console.log(data.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  # Legacy field name (reasoning_content)
  curl https://api.electronhub.ai/v1legacy/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek-r1",
      "messages": [{"role": "user", "content": "What is 2+2?"}]
    }'

  # Merged (<think> inline)
  curl https://api.electronhub.ai/v1thinking/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek-r1",
      "messages": [{"role": "user", "content": "What is 2+2?"}]
    }'

  # Hide reasoning entirely
  curl https://api.electronhub.ai/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek-r1:reasoning-exclude",
      "messages": [{"role": "user", "content": "What is 2+2?"}]
    }'
  ```
</CodeGroup>

## Streaming

Enable real-time responses with streaming:

```bash theme={null}
curl https://api.electronhub.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "Tell me a story"}
    ],
    "stream": true
  }'
```

## Function Calling

Use function calling for tool integration:

```bash theme={null}
curl https://api.electronhub.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "What is the weather like in Boston?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```


## OpenAPI

````yaml POST /chat/completions
openapi: 3.0.1
info:
  title: Electron Hub API
  description: >-
    Unified API platform integrating 200+ AI models for chat, image generation,
    speech-to-text, embeddings, and more.
  version: 1.0.0
  contact:
    name: Electron Hub Support
    email: support@electronhub.ai
    url: https://discord.com/invite/electronhub
  license:
    name: MIT
servers:
  - url: https://api.electronhub.ai/v1
    description: Production API v1
security:
  - bearerAuth: []
paths:
  /chat/completions:
    post:
      summary: Create Chat Completion
      description: >-
        Create a chat completion using OpenAI format. Reasoning models stream
        their thoughts in a separate `reasoning` field by default; see
        `/v1legacy/chat/completions` and `/v1thinking/chat/completions` for
        alternative shapes.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Model to use for completion
          example: gpt-4o
        messages:
          type: array
          description: List of messages
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
          description: Enable streaming
        max_tokens:
          type: integer
          description: Maximum tokens to generate
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: Sampling temperature
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Nucleus sampling
        top_k:
          type: integer
          description: Top-k sampling
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
        tools:
          type: array
          description: List of tools
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          oneOf:
            - type: string
              enum:
                - none
                - auto
            - $ref: '#/components/schemas/ToolChoice'
        web_search:
          type: boolean
          default: false
          description: Enable web search
        thinking:
          $ref: '#/components/schemas/ThinkingConfig'
        reasoning_effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
          description: >-
            Reasoning effort level. Silently ignored for models that do not
            support reasoning_effort, so clients can send a single shared
            request across providers.
        reasoning:
          type: object
          description: >-
            Reasoning configuration. Per-request override for reasoning output
            behavior.
          properties:
            effort:
              type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
              description: Same enum as `reasoning_effort`.
            exclude:
              type: boolean
              description: >-
                If true, strip the reasoning stream from the response entirely.
                The model still computes (and is billed for) reasoning tokens.
            delta_field:
              type: string
              enum:
                - reasoning
                - reasoning_content
              description: >-
                Override the streaming/non-streaming field name regardless of
                which endpoint variant was hit.
        reasoning_delta_field:
          type: string
          enum:
            - reasoning
            - reasoning_content
          description: Shorthand for `reasoning.delta_field`.
        reasoning_content_compat:
          type: boolean
          description: >-
            Shorthand: set to `true` to force the legacy `reasoning_content`
            field, equivalent to `reasoning.delta_field = "reasoning_content"`.
    ChatCompletionResponse:
      type: object
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
          nullable: true
          description: >-
            May be null in assistant deltas/responses when only reasoning is
            being emitted.
        reasoning:
          type: string
          nullable: true
          description: >-
            (Assistant only) The model's thinking/reasoning output, returned
            alongside `content` by `/v1/chat/completions`. Omitted when the
            model does not produce reasoning or when reasoning is excluded.
        reasoning_content:
          type: string
          nullable: true
          description: >-
            (Assistant only) Legacy field name for `reasoning`. Populated by
            `/v1legacy/chat/completions` or when `reasoning_content_compat=true`
            / `reasoning.delta_field="reasoning_content"` is set.
        name:
          type: string
          description: Name of the message author
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
    Tool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    ToolChoice:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string
    ThinkingConfig:
      oneOf:
        - type: object
          required:
            - type
            - budget_tokens
          properties:
            type:
              type: string
              enum:
                - enabled
            budget_tokens:
              type: integer
              description: Token budget for thinking
            display:
              type: string
              enum:
                - summarized
                - omitted
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - adaptive
                - disabled
            display:
              type: string
              enum:
                - summarized
                - omitted
    ChatChoice:
      type: object
      required:
        - index
        - message
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          enum:
            - stop
            - length
            - content_filter
            - tool_calls
            - function_call
    Usage:
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    ContentPart:
      oneOf:
        - $ref: '#/components/schemas/TextContentPart'
        - $ref: '#/components/schemas/ImageContentPart'
    ToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string
            arguments:
              type: string
    FunctionDefinition:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        parameters:
          type: object
    TextContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
    ImageContentPart:
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/ImageUrl'
    ImageUrl:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        detail:
          type: string
          enum:
            - low
            - high
            - auto
          default: auto
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your API key (starts with 'ek-')

````