​
VizAPI.ai API Reference

Welcome to the VizAPI.ai API reference documentation. Our API allows you to extract structured data from images, documents, and other visual content.

​
Base URL

All API requests should be made to the following base URL: 
https://api.vizapi.ai/v1

​
Authentication

VizAPI.ai uses API keys for authentication. You can obtain your API key from the VizAPI.ai dashboard. All API requests must include your API key in the x-api-key header: 
x-api-key: YOUR_API_KEY
Keep your API key secure and never expose it in client-side code or public repositories.

​
Request Format

API requests should be made using HTTPS with JSON-encoded bodies. Set the Content-Type header to application/json.

​
Image Input

VizAPI accepts images in two formats:
  1. Image URL: Provide a publicly accessible URL to your image.
  2. Base64 Encoded Image: Send the image data directly in your request as a base64-encoded data URL.
For base64 encoding, use the format: 
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...

​
Supported Image Formats

VizAPI supports the following image formats:
  • PNG - Portable Network Graphics
  • JPEG/JPG - Joint Photographic Experts Group
  • GIF - Graphics Interchange Format
  • WebP - Modern web image format
  • TIFF - Tagged Image File Format
  • BMP - Windows Bitmap
  • ICO - Windows Icon
  • SVG - Scalable Vector Graphics
  • EPS - Encapsulated PostScript
  • TGA - Truevision Graphics Adapter

​
Image Requirements

  • Maximum file size: 10MB
  • Maximum dimensions: 2048x2048 pixels (larger images will be automatically resized)
  • Images must be publicly accessible if using URLs

​
Supported Field Types

VizAPI supports the following field types for data extraction:
  • string - Text values
  • number - Numeric values (integers and decimals)
  • boolean - True/false values
  • date - Date values (extracted in various formats)
  • enum - Predefined list of possible values
  • object - Complex nested structures with subfields
  • image - AI-generated images based on extracted data and context

​
Advanced Features

​
Template Metadata Generation

When using the suggest-fields endpoint, you can request automatic generation of template metadata including title, description, category, and tags by setting with_metadata: true.

​
Multi-language Support

Extraction results can be translated to a target language by providing the target_language parameter in the advanced options.

​
Template Versioning

Templates support versioning to allow for iterative improvements while maintaining backward compatibility. When working with templates:
  • If no version_number is specified, the latest version is automatically used
  • Setting version_number to 0 also selects the latest version
  • Specifying a specific version number (e.g., 1, 2, 3) will use that exact version
  • If a requested version doesn’t exist, a 404 error will be returned

​
Image Field Generation

VizAPI supports generating images as part of data extraction. Image fields can include context from other extracted fields and support reference images to guide generation. For code snippets on how to generate base64-encoded images in various programming languages, see our Base64 Encoding Guide.

​
Response Format

All responses are returned in JSON format. A typical successful response includes: 
{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  }
}

​
Error Handling

When an error occurs, the API returns an appropriate HTTP status code and a JSON response with error details: 
{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Error message description"
  }
}
Common error codes include:
Status CodeDescription
400Bad Request - The request was malformed or missing required parameters
401Unauthorized - Invalid or missing API key
404Not Found - The requested resource was not found
429Too Many Requests - You have exceeded the rate limit for API requests
500Internal Server Error - An unexpected error occurred on our servers

​
Rate Limits

VizAPI.ai implements rate limiting to ensure fair usage of the platform. The specific limits depend on your subscription plan. When you exceed the rate limit, the API returns a 429 Too Many Requests status code with a Retry-After header indicating the number of seconds to wait before making another request.

​
Available Endpoints

VizAPI.ai provides the following main endpoints:

​
Templates

EndpointMethodDescription
/templates/GETGet a template by ID with optional version parameter
/templatesGETGet all private templates belonging to the authenticated user

​
Agents

EndpointMethodDescription
/agents/suggest-fieldsPOSTAnalyze a document and suggest fields for extraction
/agents/extract-valuesPOSTExtract values from a document using a template

​
Utility Endpoints

EndpointMethodDescription
/healthGETCheck the health status of the API

​
API Versioning

The VizAPI.ai API uses versioning to ensure backward compatibility. The current version is v1. When we make breaking changes, we’ll release a new version (e.g., v2) while maintaining support for previous versions.

​
Support

If you have any questions or need assistance with the API, please contact our support team at support@vizapi.ai.