Interfaze SDK

copy markdown

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.

Installation

npm / yarn

npm install interfaze
# or
yarn add 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.

Interfaze SDK

import { Interfaze } from "interfaze";

const interfaze = new Interfaze(); // or new Interfaze({ apiKey: "<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

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);

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.

Multimodal inputs

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

Interfaze SDK

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

Learn more about 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

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" });

Learn more about running a task.

Client options

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

Interfaze SDK

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
});

Learn more about caching and bypassing 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

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;
}

Next steps

Postgres LLM

OpenAI SDK