GitHub - itsperini/viscribe: Image intelligence layer for...

ViscribeAI

Extract structured data from images using AI models.

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

⭐ If Viscribe helps your project, please leave a star. ⭐

📦 Installation

Python:

TypeScript:

🚀 Features

🖼️ AI-powered image description, extraction, classification, VQA (Visual Question Answering), and comparison
🔄 Both sync and async clients
📊 Structured output with Pydantic schemas
🔍 Detailed logging
⚡ Automatic retries

🎯 Quick Start

from viscribe.images import describe

result = describe(
    image_path="examples/venice.png",
    # image_base64="...",
    generate_tags=True,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result)

# ImageResult(
#     data={
#         "image_description": "A scenic view of Venice...",
#         "tags": ["Venice", "canal", "gondolas"],
#     },
#     raw=<OpenAI response>,
#     usage_metadata={"input_tokens": 123, "output_tokens": 45, ...},
# )

TypeScript

import { images } from "viscribe";

const result = await images.describe({
  imagePath: "examples/venice.png",
  generateTags: true,
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result);

Note: Viscribe works with OpenAI-compatible endpoints (more support coming soon). It is recommended to load your API key from an environment variable instead of hardcoding it in your code.

📚 Image Endpoints

Method	Description
`describe`	Generate an objective image description with optional tags.
`classify`	Classify an image into one or more allowed or free-form categories.
`ask`	Ask a visual question and get an answer grounded in the image.
`extract`	Extract structured data from an image using simple fields, JSON Schema, or a Pydantic model in Python.
`compare`	Compare two images and describe their similarities and differences.

1. Describe Image

Generate a natural language description of an image, optionally with tags.

from viscribe.images import describe

result = describe(
    image_path="examples/venice.png",
    generate_tags=True,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.describe({
  imagePath: "examples/venice.png",
  generateTags: true,
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

2. Classify Image

Classify an image into one or more categories.

from viscribe.images import classify

result = classify(
    image_path="examples/venice.png",
    classes=["canal", "city", "landmark", "interior"],
    multi_label=True,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.classify({
  imagePath: "examples/venice.png",
  classes: ["canal", "city", "landmark", "interior"],
  multiLabel: true,
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

3. Visual Question Answering (VQA)

Ask a question about the content of an image and get an answer.

from viscribe.images import ask

result = ask(
    image_path="examples/venice.png",
    question="What kind of place is shown in this image?",
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.ask({
  imagePath: "examples/venice.png",
  question: "What kind of place is shown in this image?",
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

4. Extract Structured Data from Image

Extract structured data from an image using either a simple or more complex output schema.

Simple Schema

Use a simple schema for straightforward data extraction.

from viscribe.images import extract

result = extract(
    image_path="examples/venice.png",
    output_schema=[
        {"name": "location", "type": "text", "description": "Likely place shown"},
        {"name": "visible_elements", "type": "array_text", "description": "Objects and structures"},
        {"name": "colors", "type": "array_text", "description": "Dominant colors"},
    ],
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.extract({
  imagePath: "examples/venice.png",
  outputSchema: [
    { name: "location", type: "text", description: "Likely place shown" },
    {
      name: "visible_elements",
      type: "array_text",
      description: "Objects and structures",
    },
    { name: "colors", type: "array_text", description: "Dominant colors" },
  ],
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

Field Types:

text: Single text value
number: Single numeric value
array_text: Array of text values
array_number: Array of numeric values

More Complex Schema

Use a Pydantic model as the output_schema when you need complex or nested structures.

from pydantic import BaseModel
from viscribe.images import extract


class Scene(BaseModel):
    location: str
    visible_elements: list[str]
    specifications: dict


result = extract(
    image_path="examples/venice.png",
    output_schema=Scene,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.extract({
  imagePath: "examples/venice.png",
  outputSchema: {
    title: "Scene",
    type: "object",
    properties: {
      location: { type: "string" },
      visible_elements: {
        type: "array",
        items: { type: "string" },
      },
      specifications: { type: "object" },
    },
    required: ["location", "visible_elements", "specifications"],
    additionalProperties: false,
  },
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

Note: output_schema can be either a simple list of field definitions or a Pydantic model.

5. Compare Images

Compare two images and get a description of their similarities and differences.

from viscribe.images import compare

result = compare(
    image1_path="examples/venice.png",
    image2_path="examples/venice.png",
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data)

TypeScript

import { images } from "viscribe";

const result = await images.compare({
  image1Path: "examples/venice.png",
  image2Path: "examples/venice.png",
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

⚡ Async Usage

All Python endpoints support async operations with direct a* helpers:

import asyncio
from viscribe.images import adescribe


async def main() -> None:
    result = await adescribe(
        image_path="examples/venice.png",
        generate_tags=True,
        model_config={
            "model": "gpt-5-mini",
            "api_key": "sk-...",
            "temperature": 1,
        },
    )

    print(result.data)


asyncio.run(main())

You can also reuse an async client:

import asyncio
from viscribe import ViscribeAI


async def main() -> None:
    client = ViscribeAI(
        model_config={
            "model": "gpt-5-mini",
            "api_key": "sk-...",
            "temperature": 1,
        }
    )

    result = await client.images.adescribe(
        image_path="examples/venice.png",
        generate_tags=True,
    )

    print(result.data)


asyncio.run(main())

TypeScript

TypeScript is async-native, so use the same methods with await:

import { images, ViscribeAI } from "viscribe";

const result = await images.describe({
  imagePath: "examples/venice.png",
  generateTags: true,
  modelConfig: {
    model: "gpt-5-mini",
    apiKey: "sk-...",
    temperature: 1,
  },
});

console.log(result.data);

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

const clientResult = await client.images.describe({
  imagePath: "examples/venice.png",
  generateTags: true,
});

console.log(clientResult.data);

📖 Documentation

For detailed documentation, visit docs.viscribe.ai

🛠️ Development

For information about setting up the development environment and contributing to the project, see our Contributing Guide.

💬 Support & Feedback

📧 Email: support@viscribe.ai
💻 GitHub Issues: Create an issue
🌟 Feature Requests: Request a feature

🤝 Contributing

Feel free to contribute and join our Discord server to discuss with us improvements and give us suggestions!

Please see the contributing guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

⭐ If Viscribe helps your project, please leave a star. ⭐

Made with ❤️ by ViscribeAI

推荐订阅源

Hacker News - Newest: "AI"

ViscribeAI

📦 Installation

🚀 Features

🎯 Quick Start

📚 Image Endpoints

1. Describe Image

2. Classify Image

3. Visual Question Answering (VQA)

4. Extract Structured Data from Image

Simple Schema

More Complex Schema

5. Compare Images

⚡ Async Usage

📖 Documentation

🛠️ Development

💬 Support & Feedback

🤝 Contributing

📄 License

🔗 Links