Define the output schema, pass the image, pick the AI model, and get parsed structured output back instead of free-form text.

📦 Installation

npm install viscribe

🚀 Features

• 🖼️ One schema-driven images.extract helper for image workflows
• 📊 Zod schemas, JSON Schema objects, and simple field definitions
• 📁 Local image paths, base64 images, and remote image URLs
• ⚙️ Reusable new ViscribeAI().images.extract client namespace
• 🧩 OpenAI-compatible model configuration
• 🪄 Typed result wrappers for app and agent code

🎯 Quick Start

import { images } from "viscribe";

const result = await images.extract({
  imagePath: "examples/receipt.png",
  outputSchema: [
    { name: "merchant_name", type: "text", description: "Store or business name" },
    { name: "total_amount", type: "number", description: "Final total on the receipt" },
    { name: "date", type: "text", description: "Receipt date if visible" },
    { name: "line_items", type: "array_text", description: "Visible purchased items" },
  ],
  instruction: "Extract the receipt fields visible in the image.",
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

🧱 Schema Options

outputSchema accepts:

• simple field definitions
• JSON Schema objects
• Zod schemas

Simple field types are text, number, array_text, and array_number.

Zod schemas are converted to JSON Schema for the model request and validated with Zod before result.data is returned.

Strict schemas are checked against the OpenAI Structured Outputs subset before the request is sent. Unsupported schemas raise StructuredOutputSchemaError with the schema path and a suggested fix.

import { z } from "zod/v4";
import { images } from "viscribe";

const Receipt = z.object({
  merchant_name: z.string().nullish(),
  total_amount: z.number().nullish(),
});

const result = await images.extract({
  imagePath: "examples/receipt.png",
  outputSchema: Receipt,
});

console.log(result.data.total_amount);

♻️ Reusable Client

import { ViscribeAI } from "viscribe";

const client = new ViscribeAI({
  modelConfig: { model: "gpt-5-mini", temperature: 1 },
});

const result = await client.images.extract({
  imagePath: "examples/receipt.png",
  outputSchema: [{ name: "total_amount", type: "number" }],
});

💬 Support & Feedback

• 📧 Email: [email protected]
• 💻 GitHub Issues: Create an issue
• 💬 Discord: Join the community

🤝 Contributing

Please see the contributing guidelines.

🛠️ Development

npm install
npm test
npm run typecheck
npm run build
npm pack --dry-run