Template Management - VizAPI.ai docs

What Are Templates?

Templates are the brain of VizAPI.ai. They tell our AI exactly what information to extract from your images, turning visual content into clean, structured data with precision and consistency.

Smart Analysis

Define what data you want to extract with AI-powered field suggestions

Reusable & Versionable

Use the same template for similar images with full version control

Highly Customizable

7 field types, conditional logic, and multi-language support

API Ready

Instantly becomes a REST API endpoint with code examples

Creating Custom Templates

Template Builder

Our visual template builder makes creating custom templates intuitive and powerful:

Visual Editor

Point-and-click field creation with live preview

AI Suggestions

Smart field recommendations based on your content

Real-time Testing

See results as you build with confidence scoring

Version Control

Safe testing and deployment with rollback capabilities

Step-by-Step Creation

Start Building

Click “New Extraction” from your dashboard or “Create Custom Template” from the library.

Name & Describe

Give it a descriptive name and category. Add tags for better organization.

Good names: “Plant Disease Detector”, “Pose Analysis Tracker”, “Quality Inspector”

Define Fields

Add extraction fields using our comprehensive field types:

Basic Fields

String: Labels, descriptions, classifications
Number: Measurements, counts, coordinates, scores
Date: Timestamps, monitoring dates
Boolean: Yes/no, present/absent, pass/fail

Advanced Fields

Enum: Predefined lists (severity levels, categories, types)
Object: Nested structures with subfields
Image: AI-generated images based on extracted context (beta)

Configure Settings

Set up advanced options:

Required fields: Mark critical data as mandatory
return_as_list: Extract multiple instances
Multi-language: Support for 40+ languages

Test & Refine

Upload sample images to test your template. Monitor confidence scores and adjust field descriptions as needed.

Publish Template

Your template starts as a Draft. When ready, publish it to make it available for API calls.

Field Types

Field Type Overview

Each field type has specific capabilities and features:

Basic Fields
Advanced Fields
Field Configuration

String Fields

Perfect for: Labels, classifications, descriptions, object names
Supports lists: Yes
Features: Text extraction and processing

Number Fields

Perfect for: Measurements, counts, coordinates, scores, percentages
Features: Decimal precision, negative numbers, unit detection

Date Fields

Perfect for: Timestamps, monitoring dates, analysis dates
Supports: Multiple formats, relative dates, international formats

Boolean Fields

Perfect for: Present/absent, pass/fail, positive/negative
Features: True/false value extraction

Common Options:

{
  "name": "field_name",
  "description": "Detailed field description",
  "type": "string",
  "required": true,
  "return_as_list": false
}

Object Subfields:

{
  "name": "detection_results",
  "type": "object",
  "subfields": [
    {"name": "object_type", "type": "string"},
    {"name": "confidence", "type": "number"},
    {"name": "coordinates", "type": "string"}
  ]
}

Template Versioning

Version Lifecycle

Templates follow a structured lifecycle to ensure reliable API operations:

Draft

Editable: Freely modify fields, descriptions, and settings Testing: Upload images to test extraction quality Private: Not available for API calls until published

Published

Immutable: Cannot be modified directly Live: Available for API extractions Stable: Guaranteed consistent behavior for integrations

Archived

Preserved: Maintains history but not actively used Reference: Available for rollback if needed Inactive: No longer receives API traffic

Versioning Behavior

Automatic Draft Creation

Smart Versioning: When you edit a published template, the system automatically creates a new draft versionBenefits:

Protects live API integrations
Allows safe testing of changes
Preserves working versions

Workflow:

Click “Edit” on published template
System creates new draft version automatically
Make your changes in the draft
Test thoroughly before publishing

Version Control

Version Numbers: Semantic versioning (1.0, 1.1, 2.0)Publishing Flow:

Draft → Published (becomes live)
Previous version → Archived (preserved for rollback)

Rollback Capability:

Switch between any version instantly
Restore archived versions as new drafts
Complete change history tracking

API Version Control

Version-Specific Calls: Specify exact versions for production stabilityDefault Behavior: Uses latest published version if no version specifiedProduction Tip: Always specify version numbers in production to avoid unexpected changes

Version Management Workflow

Create Initial Version

New templates start as Draft v1. Define fields, test, and publish when ready.

Make Changes

Edit published templates automatically creates new draft versions. Original remains live.

Test Changes

Use draft version for testing. Previous published version continues serving API calls.

Publish Update

Publishing draft makes it live and archives the previous version.

Monitor & Rollback

Monitor performance. Can instantly rollback to previous versions if needed.

Template Performance

Key Metrics to Monitor

Success Rate

Target: Above 90% for reliable templatesOptimization Strategies:

Make optional fields truly optional
Use conditional logic for edge cases
Test with diverse image samples
Monitor field-specific failure patterns

Processing Time

Typical Range: 1-3 seconds per extractionFactors Affecting Speed:

Image size and complexity
Number of fields
Field type complexity
Batch size for multiple images

Performance Optimization

Better Descriptions

Detailed field descriptions lead to 20-30% better extraction accuracy

Quality Images

High-resolution, clear images improve confidence scores significantly

Field Optimization

Use appropriate field types that match your data requirements

Advanced Features

Conditional Fields

Extract fields only when certain conditions are met:

{
  "name": "disease_severity",
  "description": "Disease severity level, only extract if disease is detected",
  "type": "string",
  "required": false,
  "conditional": true
}

Multi-language Support

Templates can handle images with different languages:

{
  "name": "description",
  "description": "Object description",
  "type": "string",
  "target_language": "en"
}

Features:

Support for 40+ languages
Automatic language detection
Translation to target language

List Extraction

Extract multiple instances of the same field:

{
  "name": "detected_objects",
  "description": "All objects detected in the image",
  "type": "object",
  "return_as_list": true,
  "subfields": [
    {"name": "object_type", "type": "string"},
    {"name": "confidence", "type": "number"},
    {"name": "bounding_box", "type": "string"},
    {"name": "size", "type": "number"}
  ]
}

Common Issues & Solutions

Extraction Quality Issues

Problem: AI extractions are not accurate or reliableSolutions:

Improve descriptions: Add more detail about field location and format
Test image quality: Use higher resolution, better lighting
Field specificity: Be more specific about expected data format

Example Fix:

// Before (vague)
{"name": "count", "description": "The count"}

// After (specific)
{"name": "object_count", "description": "Total number of objects detected in the image, count all visible instances"}

Inconsistent Results

Problem: Same image gives different results across API callsSolutions:

Use specific versions: Pin to exact version numbers in production
Improve descriptions: Use more detailed, unambiguous field descriptions
Test variations: Validate with multiple versions of similar content

Production Best Practice:

// Always specify version in production
{
  "template_id": "pose-analyzer",
  "version_number": 2,  // Pin to specific version
  "image_url": "..."
}

Version Management Issues

Problem: Confusion about draft vs published versionsUnderstanding the System:

Draft: Editable, not available for API calls
Published: Immutable, available for API calls
Editing published: Automatically creates new draft

Best Practices:

Test thoroughly in draft before publishing
Use version numbers in production API calls
Monitor performance after publishing new versions
Keep old versions as rollback options

Best Practices

Start Simple

Begin with 3-5 core fields using basic types, then add complexity incrementally

Test Thoroughly

Use diverse, real-world images representing edge cases before publishing

Version Control

Always test new versions thoroughly and pin versions in production

Template Design Guidelines

Descriptive Names: Use clear, specific field names (object_count vs count)
Detailed Descriptions: Include location, format, and context information
Appropriate Types: Match field types to expected data formats
Smart Defaults: Make fields optional unless absolutely required
Version Management: Use semantic versioning and test before publishing

What’s Next?

API Reference

Dive deep into all available endpoints and options

Integration Examples

See real-world implementation patterns and best practices

Dashboard Guide

Master your dashboard features and template management

Support

Get help from our expert team

Remember: Great templates are built iteratively. Start simple, test often, and refine based on real-world performance. Monitor extraction quality to continuously improve your templates!

Get Started

Platform Essentials

Roadmap

​What Are Templates?

Smart Analysis

Reusable & Versionable

Highly Customizable

API Ready

​Creating Custom Templates

​Template Builder

Visual Editor

AI Suggestions

Real-time Testing

Version Control

​Step-by-Step Creation

​Field Types

​Field Type Overview

​Template Versioning

​Version Lifecycle

Draft

Published

Archived

​Versioning Behavior

​Version Management Workflow

​Template Performance

​Key Metrics to Monitor

​Performance Optimization

Better Descriptions

Quality Images

Field Optimization

​Advanced Features

​Conditional Fields

​Multi-language Support

​List Extraction

​Common Issues & Solutions

​Best Practices

Start Simple

Test Thoroughly

Version Control

​Template Design Guidelines

​What’s Next?

API Reference

Integration Examples

Dashboard Guide

Support

What Are Templates?

Creating Custom Templates

Template Builder

Step-by-Step Creation

Field Types

Field Type Overview

Template Versioning

Version Lifecycle

Versioning Behavior

Version Management Workflow

Template Performance

Key Metrics to Monitor

Performance Optimization

Advanced Features

Conditional Fields

Multi-language Support

List Extraction

Common Issues & Solutions

Best Practices

Template Design Guidelines

What’s Next?