# Interfaze SDK

URL: https://interfaze.ai/docs/integrations/interfaze-sdk

The official Interfaze SDKs are the fastest way to call Interfaze. They follow the Chat Completion API standard, so the surface is familiar, and add the Interfaze-specific parts on top: `precontext`, `reasoning`, tasks, and guardrails as typed first-class fields.

- [TypeScript / JavaScript SDK](https://www.npmjs.com/package/interfaze)
- [Python SDK](https://pypi.org/project/interfaze/)

## Installation

**npm / yarn · typescript**

```typescript
npm install interfaze
# or
yarn add interfaze
```

**pip · python**

```python
pip install interfaze
```

## Setup & authentication

The client reads `INTERFAZE_API_KEY` from the environment, so you can construct it with no arguments. Get your API key from the [dashboard](https://interfaze.ai/dashboard).

**Interfaze SDK · typescript**

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

const interfaze = new Interfaze(); // or new Interfaze({ apiKey: "<your-api-key>" })
```

**Interfaze SDK · python**

```python
from interfaze import Interfaze

interfaze = Interfaze()  # or Interfaze(api_key="<your-api-key>")
```

- No base URL or model name to configure — both are built in.
- In Python, `AsyncInterfaze` is the identical async client where every call is `await`-able.

## Your first request

**Interfaze SDK · typescript**

```typescript
import { Interfaze, responseFormat } from "interfaze";
import { z } from "zod";

const interfaze = new Interfaze();

const IDSchema = z.object({
	first_name: z.string().describe("First name on the ID"),
	last_name: z.string().describe("Last name on the ID"),
	dob: z.string().describe("Date of birth on the ID"),
	driver_licence_number: z.string().describe("Driver licence number on the ID"),
});

const response = await interfaze.chat.completions.create({
	messages: [
		{
			role: "user",
			content: [
				{ type: "text", text: "Extract the details from this ID" },
				{
					type: "image_url",
					image_url: {
						url: "https://r2public.jigsawstack.com/interfaze/examples/id.jpg",
					},
				},
			],
		},
	],
	response_format: responseFormat(z.toJSONSchema(IDSchema), "id_schema"),
});

console.log(JSON.parse(response.choices[0]?.message.content ?? "{}"));
console.log("OCR Results:", response.precontext?.[0]?.result);
```

**Interfaze SDK · python**

```python
import json
from interfaze import Interfaze, response_format

interfaze = Interfaze()

response = interfaze.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the details from this ID"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://r2public.jigsawstack.com/interfaze/examples/id.jpg"
                    },
                },
            ],
        }
    ],
    response_format=response_format(
        {
            "type": "object",
            "properties": {
                "first_name": {"type": "string", "description": "First name on the ID"},
                "last_name": {"type": "string", "description": "Last name on the ID"},
                "dob": {"type": "string", "description": "Date of birth on the ID"},
                "driver_licence_number": {"type": "string", "description": "Driver licence number on the ID"},
            },
            "required": ["first_name", "last_name", "dob", "driver_licence_number"],
        },
        "id_schema",
    ),
)

print(json.loads(response.choices[0].message.content or "{}"))
print("OCR Results:", response.precontext[0].result if response.precontext else None)
```

- `response_format()` normalizes a JSON Schema for Interfaze. In TypeScript, pass a Zod schema through `z.toJSONSchema()`.
- `message.content` is a JSON string, so parse it. Keep the schema root an `object`, since a non-object root is wrapped under a `result` key.
- `precontext` carries the raw metadata behind the answer, such as bounding boxes and confidence scores. Learn more about [precontext](https://interfaze.ai/docs/precontext).

## Multimodal inputs

`inputs.*` builds content parts for you, and turns raw bytes or a local file into a data URI.

**Interfaze SDK · typescript**

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

inputs.image("https://r2public.jigsawstack.com/interfaze/examples/id.jpg"); // image_url part
inputs.file("https://arxiv.org/pdf/1706.03762"); // file part
inputs.audio("https://r2public.jigsawstack.com/interfaze/examples/stt_medical_short.mp4"); // input_audio part
inputs.image(await inputs.fromPath("./photo.png")); // read a local file (Node only)
inputs.file(await inputs.dataUrl(pdfBytes, "application/pdf"), { filename: "report.pdf" }); // raw bytes / Blob
```

**Interfaze SDK · python**

```python
from interfaze import inputs

inputs.image("https://r2public.jigsawstack.com/interfaze/examples/id.jpg")  # image_url part
inputs.file("https://arxiv.org/pdf/1706.03762")  # file part
inputs.audio("https://r2public.jigsawstack.com/interfaze/examples/stt_medical_short.mp4")  # input_audio part
inputs.image(inputs.from_path("./photo.png"))  # read a local file
inputs.file(inputs.data_url(pdf_bytes, "application/pdf"), filename="report.pdf")  # raw bytes
```

Learn more about [handling files](https://interfaze.ai/docs/handling-files).

## Tasks

`tasks.*` runs a single built-in tool instead of the full model, which is faster and cheaper. Each helper takes a source and returns the raw result.

**Interfaze SDK · typescript**

```typescript
await interfaze.tasks.ocr(url);
await interfaze.tasks.objectDetection(url);
await interfaze.tasks.guiDetection(url);
await interfaze.tasks.webSearch(query);
await interfaze.tasks.scrape(url);
await interfaze.tasks.transcribe(url);
await interfaze.tasks.translate(text, { to: "Spanish" });
await interfaze.tasks.forecast(csvUrl, { periods: 30, unit: "days" });
```

**Interfaze SDK · python**

```python
interfaze.tasks.ocr(url)
interfaze.tasks.object_detection(url)
interfaze.tasks.gui_detection(url)
interfaze.tasks.web_search(query)
interfaze.tasks.scrape(url)
interfaze.tasks.transcribe(url)
interfaze.tasks.translate(text, to="Spanish")
interfaze.tasks.forecast(csv_url, periods=30, unit="days")
```

Learn more about [running a task](https://interfaze.ai/docs/run-tasks).

## Client options

Router, cache, and streaming behaviour can be set once on the client.

**Interfaze SDK · typescript**

```typescript
const interfaze = new Interfaze({
	showAdditionalInfo: true, // stream <precontext> deltas as they're produced
	bypassMoA: true, // skip the mixture-of-architecture router
	bypassCache: true, // skip the semantic cache
});
```

**Interfaze SDK · python**

```python
interfaze = Interfaze(
    show_additional_info=True,  # stream <precontext> deltas as they're produced
    bypass_moa=True,            # skip the mixture-of-architecture router
    bypass_cache=True,          # skip the semantic cache
)
```

Learn more about [caching](https://interfaze.ai/docs/caching) and [bypassing MoA](https://interfaze.ai/docs/bypass-moa).

## Errors

Every error class is exported so you can catch and narrow on it. `InterfazeError` covers client-side problems like a missing key or an invalid guard code. Everything else is an `APIError` subclass carrying the status and code, such as `BadRequestError` (400), `AuthenticationError` (401), and `RateLimitError` (429).

**Interfaze SDK · typescript**

```typescript
import { BadRequestError, InterfazeError, RateLimitError } from "interfaze";

try {
	await interfaze.chat.completions.create({ messages: [{ role: "user", content: "Hello" }] });
} catch (error) {
	if (error instanceof RateLimitError) console.error("Slow down:", error.status);
	else throw error;
}
```

**Interfaze SDK · python**

```python
from interfaze import BadRequestError, InterfazeError, RateLimitError

try:
    interfaze.chat.completions.create(messages=[{"role": "user", "content": "Hello"}])
except RateLimitError as error:
    print("Slow down:", error.status_code)
```

## Next steps

- [Structured outputs](https://interfaze.ai/docs/structured-output)
- [Streaming](https://interfaze.ai/docs/streaming)
- [Reasoning](https://interfaze.ai/docs/reasoning)
- [Function calling](https://interfaze.ai/docs/function-calling)
- [Guardrails](https://interfaze.ai/docs/guardrails)
- [Chat Completion API reference](https://interfaze.ai/docs/api/chat-completion)