# Chat Completion API

URL: https://interfaze.ai/docs/api/chat-completion

## Base URL

```text
https://api.interfaze.ai/v1
```

## Authentication

All requests must be authenticated with an API key passed in the `Authorization` header as a Bearer token.

```text
Authorization: Bearer <your-api-key>
```

Create and manage API keys from the [dashboard](https://interfaze.ai/dashboard).

## Create chat completion

Creates a model response for the given chat conversation.

```text
POST https://api.interfaze.ai/v1/chat/completions
```

### Request headers

| Header                     | Required | Description                                                                                                              |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Authorization`            | Yes      | `Bearer <your-api-key>`                                                                                                  |
| `Content-Type`             | Yes      | `application/json`                                                                                                       |
| `x-show-additional-info`   | No       | Set to `true` to include [precontext](https://interfaze.ai/docs/precontext) inline at the start of a streamed response. Defaults to `false`. |
| `x-interfaze-zdr`          | No       | Set to `true` for [zero data retention](https://interfaze.ai/docs/security#zero-data-retention-zdr). Defaults to `false`.                    |
| `x-interfaze-bypass-cache` | No       | Set to `true` to skip the verified [cache](https://interfaze.ai/docs/caching) and run the request fresh. Defaults to `false`.                |
| `x-interfaze-bypass-moa`   | No       | Set to `true` to [bypass MoA](https://interfaze.ai/docs/bypass-moa) and run only the raw model layer. Defaults to `false`.                   |

### Example request

**cURL · bash**

```bash
curl https://api.interfaze.ai/v1/chat/completions \
  -H "Authorization: Bearer $INTERFAZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "interfaze-beta",
    "messages": [
      { "role": "user", "content": "Who is the founder of Interfaze?" }
    ]
  }'
```

**fetch · typescript**

```typescript
const response = await fetch("https://api.interfaze.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.INTERFAZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "interfaze-beta",
    messages: [
      { role: "user", content: "Who is the founder of Interfaze?" },
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

**Interfaze SDK · typescript**

```typescript
import { Interfaze } from "interfaze";

const interfaze = new Interfaze({
  apiKey: process.env.INTERFAZE_API_KEY,
});

const response = await interfaze.chat.completions.create({
  messages: [
    { role: "user", content: "Who is the founder of Interfaze?" },
  ],
});

console.log(response.choices[0]?.message.content);
```

**Vercel AI SDK · typescript**

```typescript
import { createInterfaze } from "@interfaze-ai/ai-sdk";
import { generateText } from "ai";

const interfaze = createInterfaze({
  apiKey: process.env.INTERFAZE_API_KEY,
});

const { text } = await generateText({
  model: interfaze("interfaze-beta"),
  prompt: "Who is the founder of Interfaze?",
});

console.log(text);
```

**LangChain SDK · typescript**

```typescript
import { ChatInterfaze } from "@interfaze-ai/langchain";

const interfaze = new ChatInterfaze({
  apiKey: process.env.INTERFAZE_API_KEY,
});

const response = await interfaze.invoke("Who is the founder of Interfaze?");

console.log(response.content);
```

**requests · python**

```python
import os
import requests

response = requests.post(
    "https://api.interfaze.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['INTERFAZE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "interfaze-beta",
        "messages": [
            {"role": "user", "content": "Who is the founder of Interfaze?"},
        ],
    },
)

print(response.json()["choices"][0]["message"]["content"])
```

**Interfaze SDK · python**

```python
import os
from interfaze import Interfaze

interfaze = Interfaze(
    api_key=os.environ["INTERFAZE_API_KEY"],
)

response = interfaze.chat.completions.create(
    messages=[
        {"role": "user", "content": "Who is the founder of Interfaze?"},
    ],
)

print(response.choices[0].message.content)
```

**LangChain SDK · python**

```python
import os
from interfaze_langchain import ChatInterfaze

interfaze = ChatInterfaze(
    api_key=os.environ["INTERFAZE_API_KEY"],
)

response = interfaze.invoke("Who is the founder of Interfaze?")

print(response.content)
```

## Body parameters

Summary of fields accepted on the request body. Each parameter is fully documented below.

| Parameter          | Type             | Required | Default          |
| ------------------ | ---------------- | -------- | ---------------- |
| `model`            | string           | Yes      | —                |
| `messages`         | array            | Yes      | —                |
| `stream`           | boolean          | No       | `false`          |
| `response_format`  | object           | No       | `{type: "text"}` |
| `tools`            | array            | No       | —                |
| `tool_choice`      | string \| object | No       | `"auto"`         |
| `reasoning_effort` | string           | No       | off              |
| `max_tokens`       | integer          | No       | `32000`          |
| `temperature`      | number           | No       | `1`              |
| `top_p`            | number           | No       | `1`              |

### `model`

**Type:** `string` &nbsp;·&nbsp; **Required**

The id of the model to use. Currently the only supported value is `interfaze-beta`.

```json
{ "model": "interfaze-beta" }
```

### `messages`

**Type:** `array` &nbsp;·&nbsp; **Required**

A list of messages making up the conversation so far. Each item is a message object.

| Field          | Type            | Required           | Description                                                                                       |
| -------------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
| `role`         | string          | Yes                | One of `system`, `user`, `assistant`, or `tool`.                                                  |
| `content`      | string \| array | Yes                | Either a plain string or an array of [content parts](#content-parts) for multimodal input.        |
| `name`         | string          | No                 | Optional name of the participant.                                                                 |
| `tool_calls`   | array           | Assistant only     | Tool calls the model wants the caller to execute. See [Function calling](https://interfaze.ai/docs/function-calling). |
| `tool_call_id` | string          | Tool messages only | The id of the tool call this message is responding to.                                            |

```json
{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Who is the founder of Interfaze?" }
  ]
}
```

#### Content parts

When `content` is an array, each item is a typed part. Mix and match to send multimodal input (text + images + files in a single message).

##### Text part

| Field  | Type   | Required | Description       |
| ------ | ------ | -------- | ----------------- |
| `type` | string | Yes      | Must be `"text"`. |
| `text` | string | Yes      | The text content. |

```json
{
  "type": "text",
  "text": "Extract the details from this ID"
}
```

##### Image part

| Field           | Type   | Required | Description                                                                |
| --------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `type`          | string | Yes      | Must be `"image_url"`.                                                     |
| `image_url`     | object | Yes      | Wrapper object containing the image source.                                |
| `image_url.url` | string | Yes      | Publicly accessible URL or base64 data URL (`data:image/jpeg;base64,...`). |

```json
{
  "type": "image_url",
  "image_url": {
    "url": "https://r2public.jigsawstack.com/interfaze/examples/id.jpg"
  }
}
```

##### File part

For PDFs, audio, video, and other documents.

| Field            | Type   | Required | Description                                                            |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `type`           | string | Yes      | Must be `"file"`.                                                      |
| `file`           | object | Yes      | Wrapper object containing the file source.                             |
| `file.filename`  | string | Yes      | Filename including extension. Used for MIME inference.                 |
| `file.file_data` | string | Yes      | Publicly accessible URL or base64 data URL (`data:<mime>;base64,...`). |

```json
{
  "type": "file",
  "file": {
    "filename": "report.pdf",
    "file_data": "https://example.com/report.pdf"
  }
}
```

See [Handling files](https://interfaze.ai/docs/handling-files) for size limits and SDK-specific helpers.

### `stream`

**Type:** `boolean` &nbsp;·&nbsp; **Default:** `false`

If `true`, partial message deltas are sent as server-sent events as they are generated. The stream terminates with `data: [DONE]`. See the [Streaming](#streaming) section for the chunk format and [Streaming](https://interfaze.ai/docs/streaming) for SDK examples.

```json
{ "stream": true }
```

### `response_format`

**Type:** `object` &nbsp;·&nbsp; **Default:** plain text

Constrains the model output to a specific format. Follows the [OpenAI structured output specification](https://developers.openai.com/api/docs/guides/structured-outputs?api-mode=chat).

| Field         | Type   | Required                       | Description                            |
| ------------- | ------ | ------------------------------ | -------------------------------------- |
| `type`        | string | Yes                            | `"text"` (default) or `"json_schema"`. |
| `json_schema` | object | When `type` is `"json_schema"` | The JSON schema configuration.         |

When `type` is `"json_schema"`, `json_schema` accepts:

| Field    | Type    | Required | Description                                                  |
| -------- | ------- | -------- | ------------------------------------------------------------ |
| `name`   | string  | Yes      | Identifier for the schema (e.g. `"id_schema"`).              |
| `schema` | object  | Yes      | A valid JSON Schema definition describing the output shape.  |
| `strict` | boolean | No       | Whether to strictly enforce the schema. Defaults to `false`. |

```json
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "id_schema",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "first_name": { "type": "string" },
          "last_name": { "type": "string" }
        },
        "required": ["first_name", "last_name"],
        "additionalProperties": false
      }
    }
  }
}
```

See [Structured Outputs](https://interfaze.ai/docs/structured-output) for full examples.

### `tools`

**Type:** `array` &nbsp;·&nbsp; **Optional**

A list of tools (functions) the model may call. Follows the [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling?api-mode=chat) schema.

Each tool object:

| Field                  | Type   | Required | Description                                                     |
| ---------------------- | ------ | -------- | --------------------------------------------------------------- |
| `type`                 | string | Yes      | Always `"function"`.                                            |
| `function`             | object | Yes      | The function definition.                                        |
| `function.name`        | string | Yes      | Unique function name (snake_case recommended).                  |
| `function.description` | string | No       | What the function does. Helps the model decide when to call it. |
| `function.parameters`  | object | No       | JSON Schema describing the function's arguments.                |

```json
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_horoscope",
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
          "type": "object",
          "properties": {
            "sign": {
              "type": "string",
              "description": "An astrological sign like Taurus or Aquarius"
            }
          },
          "required": ["sign"]
        }
      }
    }
  ]
}
```

See [Function calling](https://interfaze.ai/docs/function-calling) for the full multi-turn flow.

### `tool_choice`

**Type:** `string | object` &nbsp;·&nbsp; **Default:** `"auto"`

Controls which (if any) tool the model calls.

| Value                                                  | Behavior                                          |
| ------------------------------------------------------ | ------------------------------------------------- |
| `"auto"`                                               | The model decides whether and which tool to call. |
| `"none"`                                               | The model will not call any tool.                 |
| `"required"`                                           | The model must call at least one tool.            |
| `{"type": "function", "function": {"name": "<name>"}}` | Forces the model to call the specified function.  |

```json
{
  "tool_choice": { "type": "function", "function": { "name": "get_horoscope" } }
}
```

### `reasoning_effort`

**Type:** `string` &nbsp;·&nbsp; **Default:** off

Enables extended reasoning. The model spends more compute and thinking tokens before producing a final answer.

| Value      | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `"low"`    | Light reasoning pass.                                          |
| `"medium"` | Moderate reasoning.                                            |
| `"high"`   | Deep reasoning. Recommended for math, science, complex agents. |

When set, the response contains a `reasoning` field with the model's thinking trace. In streaming mode, reasoning tokens stream first inside `<think>...</think>` tags.

```json
{ "reasoning_effort": "high" }
```

See [Reasoning](https://interfaze.ai/docs/reasoning) for details.

### `max_tokens`

**Type:** `integer` &nbsp;·&nbsp; **Default:** `32000`

The maximum number of tokens to generate in the completion. Hard upper bound of 32,000 tokens. Input tokens + `max_tokens` cannot exceed the 1M context window.

```json
{ "max_tokens": 1024 }
```

### `temperature`

**Type:** `number` &nbsp;·&nbsp; **Default:** `1`

Sampling temperature between `0` and `2`. Higher values produce more random output, lower values make the output more focused and deterministic. Use `0` together with a `seed` for the most reproducible results.

```json
{ "temperature": 0.2 }
```

### `top_p`

**Type:** `number` &nbsp;·&nbsp; **Default:** `1`

Nucleus sampling. The model considers only the tokens whose cumulative probability mass is `top_p`. `0.1` means only the top 10% of probability mass is sampled from. Generally only adjust one of `temperature` or `top_p`.

```json
{ "top_p": 0.9 }
```

## System prompt extensions

Interfaze recognizes two special XML-style directives inside the system message that change how the model behaves.

### `<task>` — run a single built-in task

Run a specialized part of the model directly without invoking the full LLM. Faster, cheaper, and returns a fixed precontext schema. The `response_format` must be an open/empty JSON schema (`any` type).

```text
<task>ocr</task>
```

| Task               | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `ocr`              | Optical character recognition on images and documents |
| `object_detection` | Detect objects in images                              |
| `gui_detection`    | Detect GUI elements in images                         |
| `web_search`       | Web search                                            |
| `scraper`          | Extract structured data from web pages                |
| `speech_to_text`   | Speech to text transcription                          |
| `translate`        | Translation                                           |

See [Run Tasks](https://interfaze.ai/docs/run-tasks).

### `<guard>` — content safety guardrails

Block or flag unsafe content matching one or more safety codes.

```text
<guard>S1, S2, S3, S10, S12_IMAGE</guard>
```

Supported codes: `S1`, `S1_IMAGE`, `S2`, `S3`, `S4`, `S5`, `S6`, `S7`, `S8`, `S9`, `S10`, `S11`, `S12`, `S12_IMAGE`, `S13`, `S14`, `S15_IMAGE`, `ALL`.

See [Guardrails](https://interfaze.ai/docs/guardrails) for the full list and behavior.

## Response object

A successful non-streaming response returns a chat completion object that follows the OpenAI shape with one Interfaze-specific addition: the top-level `precontext` field.

| Field        | Type    | Description                                                                                                         |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`         | string  | Unique identifier for the completion.                                                                               |
| `object`     | string  | Always `chat.completion`.                                                                                           |
| `model`      | string  | The model used.                                                                                                     |
| `choices`    | array   | A list of completion choices. Each contains an `index`, `message`, and `finish_reason`.                             |
| `usage`      | object  | Token usage: `prompt_tokens`, `completion_tokens`, `total_tokens`.                                                  |
| `reasoning`  | string  | Present when `reasoning_effort` is set. The model's thinking trace.                                                 |
| `precontext` | array   | Raw outputs from any internal tasks the model ran (OCR, STT, web search, etc.). See [precontext](https://interfaze.ai/docs/precontext). |
| `vcache`     | boolean | Whether the response was served from the model's verified cache.                                                    |

### Example response

```json
{
  "id": "interfaze-1775270750639",
  "object": "chat.completion",
  "model": "interfaze-beta",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"Yoeven D Khemlani\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10512,
    "completion_tokens": 7056,
    "total_tokens": 17568
  },
  "vcache": false,
  "precontext": [
    {
      "name": "web_search",
      "result": [
        {
          "title": "Interfaze | Y Combinator",
          "url": "https://www.ycombinator.com/companies/interfaze",
          "description": "AI model built for deterministic developer tasks."
        }
      ]
    }
  ]
}
```

## Streaming

Set `"stream": true` in the request body to receive deltas as server-sent events. Each chunk follows the OpenAI streaming format:

```text
data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hel"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"lo"},"finish_reason":null}]}

data: [DONE]
```

### Streaming with precontext

By default, streamed responses do not include `precontext`. To opt in, add the header:

```text
x-show-additional-info: true
```

When enabled, a single chunk containing the precontext is emitted **before** the main response begins. It is wrapped in XML tags inside the content delta so you can parse it from the stream:

```xml
<precontext>
{
  "name": "ocr",
  "result": { ... }
}
</precontext>
```

### Streaming with reasoning

When `reasoning_effort` is set and `stream` is `true`, reasoning tokens are delivered first, wrapped in `<think>` tags:

```xml
<think>
Thinking step 1...
Thinking step 2...
</think>

Final answer begins here...
```

See [Reasoning](https://interfaze.ai/docs/reasoning) and [Streaming](https://interfaze.ai/docs/streaming) for more.

## Errors

Errors follow the OpenAI error shape and use standard HTTP status codes.

```json
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

| Status | Type                    | Meaning                                                                         |
| ------ | ----------------------- | ------------------------------------------------------------------------------- |
| 400    | `invalid_request_error` | The request body is malformed or missing required fields.                       |
| 401    | `authentication_error`  | The API key is missing, invalid, or revoked.                                    |
| 402    | `insufficient_quota`    | Your account has insufficient credits. Top up from the [dashboard](https://interfaze.ai/dashboard). |
| 413    | `payload_too_large`     | Request body or input file exceeds size limits. See [Limits](https://interfaze.ai/docs/limits).     |
| 429    | `rate_limit_error`      | You exceeded the rate limit. Retry with exponential backoff.                    |
| 500    | `internal_error`        | Server-side failure. Safe to retry.                                             |
| 503    | `service_unavailable`   | Temporary capacity issue. Retry with backoff.                                   |