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:
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:
Keep your API key secure and never expose it in client-side code or public repositories.
Content-Type header to application/json.
VizAPI accepts images in two formats:
- Image URL: Provide a publicly accessible URL to your image.
- 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...
- 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
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.
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"
}
}
| Status Code | Description |
|---|
| 400 | Bad Request - The request was malformed or missing required parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - The requested resource was not found |
| 429 | Too Many Requests - You have exceeded the rate limit for API requests |
| 500 | Internal 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
| Endpoint | Method | Description |
|---|
| /templates/ | GET | Get a template by ID with optional version parameter |
| /templates | GET | Get all private templates belonging to the authenticated user |
Agents
| Endpoint | Method | Description |
|---|
| /agents/suggest-fields | POST | Analyze a document and suggest fields for extraction |
| /agents/extract-values | POST | Extract values from a document using a template |
Utility Endpoints
| Endpoint | Method | Description |
|---|
| /health | GET | Check 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 [email protected].