Introduction

copy markdown

This guide will get you started and make your first request to Interfaze with the official Interfaze SDK, or any AI SDK that supports the Chat Completion API standard.

Model specs

Feature	Value
Context window	1m tokens
Max output tokens	32k tokens
Input modalities	Text, Images, Audio, File, Video
Reasoning	Available (default: disabled)

View limits here | View pricing here

Prerequisites

The Interfaze SDK installed (npm install interfaze or pip install interfaze), or an AI SDK of your choice
On the Vercel AI SDK, install the native Vercel AI SDK provider instead (npm install @interfaze-ai/ai-sdk)
On LangChain, install the native LangChain integration instead (npm install @interfaze-ai/langchain or pip install interfaze-langchain)
If you're using another AI SDK, replace the base URL with https://api.interfaze.ai/v1
Get your API key from the dashboard.

Set up SDK & authentication

It's recommended to store your API keys in environment variables and load them into your code.

Interfaze SDK

Vercel AI SDK

LangChain SDK

import { Interfaze } from "interfaze";

// reads INTERFAZE_API_KEY from the environment
const interfaze = new Interfaze();

You can create, rotate, or revoke API keys anytime from the dashboard.

Make your first request

Let's extract the details from an ID image

Interfaze SDK

Vercel AI SDK

LangChain SDK

import { responseFormat } from "interfaze";
import { z } from "zod";

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

Structured output is the best way to control the output of the model.
precontext contains the raw metadata such as bounding boxes and confidence scores. Learn more about precontext.
Here we passed the image as a file which converts it to base64 automatically but you can also pass the url in the prompt directly. Learn more about the different ways to handle files.

Files

Audio handling to transcribe audio files.

Interfaze SDK

Vercel AI SDK

LangChain SDK

import { inputs, responseFormat } from "interfaze";
import { z } from "zod";

const STTSchema = z.object({
	text: z.string(),
});

const response = await interfaze.chat.completions.create({
	messages: [
		{
			role: "user",
			content: [
				{ type: "text", text: "Transcribe the audio file" },
				inputs.file("https://r2public.jigsawstack.com/interfaze/examples/stt_medical_short.mp4", {
					filename: "stt_medical_short.mp4",
				}),
			],
		},
	],
	response_format: responseFormat(z.toJSONSchema(STTSchema), "stt_schema"),
});

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

Files supported: images, documents, audio, video
Both base64 and URL are natively supported for all files.
Files can either be passed as a file object or a URL in the prompt directly.

Learn more about the different ways to handle files.

Common use case examples

Run tasks

Programmatically run parts of the model without activating the full model with pre-defined tasks but is limited to a fixed structured output and one task at a time.

Learn more about running a task.

Interfaze SDK

Vercel AI SDK

LangChain SDK

import { inputs } from "interfaze";

const response = await interfaze.chat.completions.create({
	task: "object_detection",
	messages: [
		{
			role: "user",
			content: [
				{ type: "text", text: "Get the position of the crane in the image and any text" },
				inputs.image("https://r2public.jigsawstack.com/interfaze/examples/construction.png"),
			],
		},
	],
});

const { result } = JSON.parse(response.choices[0]?.message.content ?? "{}");
console.log(result);

Faster and cheaper than the full model.
Guaranteed and fixed structured output that is pre-defined.
Great for use cases where you are using the result as part of a larger pipeline.

Guardrails

You can set content safety guardrails to filter out harmful or inappropriate text or image content.

Learn more about guardrails.

Interfaze SDK

Vercel AI SDK

LangChain SDK

const response = await interfaze.chat.completions.create({
    guard: ["S1", "S2", "S3", "S10", "S11", "S12_IMAGE", "S15_IMAGE"],
    messages: [
        {
            role: "user",
            content: "How to make a bomb with household items"
        }
    ],
});

// returns the plain string "unsafe S1" when a category matches
console.log(response.choices[0]?.message.content);

OCR (Image & Document)