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 valuenumber: Single numeric valuearray_text: Array of text valuesarray_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_schemacan 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