Python SDK
The official Python SDK provides a simple and intuitive interface for interacting with the ViscribeAI API.
Installation
Quick Start
from viscribe import Client
client = Client(api_key="your-api-key-here")
You can set the VISCRIBE_API_KEY environment variable and initialize the client without parameters: client = Client()
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
- 🔐 Secure authentication
Image Endpoints
1. Describe Image
Generate a natural language description of an image, optionally with tags.
from viscribe import Client
client = Client(api_key="your-api-key-here")
# Using image URL
resp = client.describe_image(
image_url="https://img.com/cat.jpg",
generate_tags=True
)
# Or using base64 encoded image
# resp = client.describe_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# generate_tags=True
# )
print(resp.image_description)
print(resp.tags)
2. Classify Image
Classify an image into one or more categories.
# Using image URL
resp = client.classify_image(
image_url="https://img.com/cat.jpg",
classes=["cat", "dog"]
)
# Or using base64 encoded image
# resp = client.classify_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# classes=["cat", "dog"]
# )
print(resp.classification)
3. Visual Question Answering (VQA)
Ask a question about the content of an image and get an answer.
# Using image URL
resp = client.ask_image(
image_url="https://img.com/car.jpg",
question="What color is the car?"
)
# Or using base64 encoded image
# resp = client.ask_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# question="What color is the car?"
# )
print(resp.answer)
# Using image URL
resp = client.extract_image(
image_url="https://img.com/prod.jpg",
fields=[
{"name": "product_name", "type": "text", "description": "Name of the product"},
{"name": "price", "type": "number", "description": "Product price"},
{"name": "tags", "type": "array_text", "description": "Product tags"},
]
)
# Or using base64 encoded image
# resp = client.extract_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# fields=[
# {"name": "product_name", "type": "text", "description": "Name of the product"},
# {"name": "price", "type": "number", "description": "Product price"},
# {"name": "tags", "type": "array_text", "description": "Product tags"},
# ]
# )
print(resp.extracted_data)
text: Single text valuenumber: Single numeric valuearray_text: Array of text values (max 5 items)array_number: Array of numeric values (max 5 items)
Advanced Schema (For complex/nested structures)
Use advanced schema for complex nested structures or when you need more control:
from pydantic import BaseModel
class Product(BaseModel):
product_name: str
price: float
specifications: dict
# Using image URL
resp = client.extract_image(
image_url="https://img.com/prod.jpg",
advanced_schema=Product # Pass the class directly
)
# Or using base64 encoded image
# resp = client.extract_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# advanced_schema=Product
# )
print(resp.extracted_data)
Either fields or advanced_schema must be provided, not both.
5. Compare Images
Compare two images and get a description of their similarities and differences.
# Using image URLs
resp = client.compare_images(
image1_url="https://img.com/cat1.jpg",
image2_url="https://img.com/cat2.jpg"
)
# Or using base64 encoded images
# resp = client.compare_images(
# image1_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...",
# image2_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
# )
# Or mix and match (one URL, one base64)
# resp = client.compare_images(
# image1_url="https://img.com/cat1.jpg",
# image2_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
# )
print(resp.comparison_result)
User Endpoints
Get Credits
Check your remaining credits and total usage:
credits = client.get_credits()
print(f"Remaining credits: {credits.remaining_credits}")
print(f"Total credits used: {credits.total_credits_used}")
Submit Feedback
Provide feedback on API responses to help improve the service:
# First, make an API call to get a request_id
response = client.describe_image(
image_url="https://example.com/image.jpg"
)
# Then submit feedback for that request
feedback_response = client.submit_feedback(
request_id=response.request_id,
rating=5, # Rating from 0-5
feedback_text="Perfect image description!",
)
print(f"Feedback ID: {feedback_response.feedback_id}")
-
Image URL: Provide a publicly accessible URL
resp = client.describe_image(image_url="https://example.com/image.jpg")
-
Base64 Encoding: Encode your image as base64
resp = client.describe_image(image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg...")
You must provide either image_url or image_base64, not both. For the Compare endpoint, you can mix and match (e.g., image1_url with image2_base64).
Async Usage
All endpoints support async operations:
import asyncio
from viscribe import AsyncClient
async def main():
client = AsyncClient(api_key="your-api-key-here")
# Using image URL
resp = await client.describe_image(
image_url="https://img.com/cat.jpg"
)
# Or using base64
# resp = await client.describe_image(
# image_base64="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
# )
print(resp)
# ... use other endpoints as above
asyncio.run(main())
Error Handling
The SDK automatically handles common errors and provides helpful error messages:
from viscribe import Client, ViscribeError
client = Client(api_key="your-api-key-here")
try:
resp = client.describe_image(image_url="https://img.com/cat.jpg")
except ViscribeError as e:
print(f"API Error: {e}")
Resources
Support
