Skip to main content

​
Overview

ViscribeAI provides a RESTful API for analyzing images using advanced AI models. All endpoints are authenticated and return structured JSON responses.

​
Base URL

All API requests should be made to: 
https://api.viscribe.ai/v1
All endpoints are prefixed with /v1. For example:
  • Image endpoints: /v1/images/describe, /v1/images/extract, etc.
  • User endpoints: /v1/credits, /v1/feedback

​
Authentication

All API endpoints require authentication using the VISCRIBE-APIKEY header. This header must be included in every request: 
VISCRIBE-APIKEY: YOUR_API_KEY
Example: 
curl -X GET https://api.viscribe.ai/v1/credits \
  -H "VISCRIBE-APIKEY: YOUR_API_KEY"
You can obtain your API key from the dashboard.

​
Endpoints

ViscribeAI offers five main image analysis endpoints:

Describe Image

Generate detailed textual descriptions of images with optional tags and SEO optimization.

Extract Data

Extract structured data from receipts, invoices, forms, and documents.

Classify Image

Classify images into predefined categories with zero-shot learning support.

Ask Question

Ask specific questions about image content for detailed visual analysis.

Compare Images

Compare two images side-by-side to identify similarities and differences.

​
User Endpoints

Get Credits

Check your remaining credits and total usage.

Submit Feedback

Provide feedback on API responses to help improve the service.

​
Request Format

All requests (GET and POST) must include:
  • VISCRIBE-APIKEY: YOUR_API_KEY header (required for all endpoints)
  • Content-Type: application/json header (required for POST requests)
  • JSON body with required parameters (for POST requests)
Example GET request: 
curl -X GET https://api.viscribe.ai/v1/credits \
  -H "VISCRIBE-APIKEY: YOUR_API_KEY"
Example POST request: 
# Using image URL
curl -X POST https://api.viscribe.ai/v1/images/describe \
  -H "VISCRIBE-APIKEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/image.jpg"}'

# Or using base64 encoded image
curl -X POST https://api.viscribe.ai/v1/images/describe \
  -H "VISCRIBE-APIKEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}'

​
Response Format

All successful responses return JSON with the following structure: 
{
  "request_id": "uuid",
  "credits_used": 2,
  // ... endpoint-specific response data
}

​
Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 402 - Payment Required (insufficient credits)
  • 422 - Unprocessable Entity (validation errors)
  • 500 - Internal Server Error
Error responses include a JSON body with error details: 
{
  "error": "Error message description"
}

​
Rate Limits

Rate limits vary by subscription plan:
  • Free Trial: 5 requests per minute
  • Starter: 10 requests per minute
  • Growth: 30 requests per minute
  • Pro: 100 requests per minute
Rate limit headers are included in responses:
  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets

​
Credits

Each API call consumes credits based on the endpoint:
  • Describe: 1 credit
  • Extract: 1 credit
  • Classify: 1 credit
  • Ask: 1 credit
  • Compare: 2 credits (counts as 2 images)
Check your remaining credits using the Get Credits endpoint or in your dashboard.

​
Image Input

You can provide images in two ways:
  1. Image URL: Provide a publicly accessible URL 
    {
  "image_url": "https://example.com/image.jpg"
}
  2. Base64 Encoding: Encode your image as base64 (with data URI prefix) 
    {
  "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).
Supported formats: JPEG, PNG, WebP, GIF Base64 Format: The base64 string should include the data URI prefix: data:image/{format};base64,{base64_encoded_data} For example:
  • JPEG: data:image/jpeg;base64,/9j/4AAQSkZJRg...
  • PNG: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
  • WebP: data:image/webp;base64,UklGRiQAAABXRUJQVlA4...

​
SDKs

Official SDKs are available to simplify integration:

Python SDK

Full-featured Python SDK with sync and async support. Install with pip install viscribe.
For detailed SDK documentation and examples, see the SDK Guide.

​
OpenAPI Specification

FastAPI automatically generates an OpenAPI specification for all endpoints. You can access it at:
  • OpenAPI JSON: https://api.viscribe.ai/openapi.json
  • Interactive Docs: https://api.viscribe.ai/docs (Swagger UI)
  • ReDoc: https://api.viscribe.ai/redoc
The OpenAPI specification includes all endpoints, request/response schemas, and authentication requirements. You can use it to generate client libraries, test the API, or integrate with API documentation tools.