> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vizapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Template Management

> Create and manage extraction templates that turn your visual content into structured data

<img style={{ borderRadius: '0.5rem' }} src="https://vizapi.ai/images/template-builder.png" alt="VizAPI.ai Template Builder" />

## 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.

<CardGroup cols={2}>
  <Card title="Smart Analysis" icon="file">
    Define what data you want to extract with AI-powered field suggestions
  </Card>

  <Card title="Reusable & Versionable" icon="recycle">
    Use the same template for similar images with full version control
  </Card>

  <Card title="Highly Customizable" icon="wrench">
    7 field types, conditional logic, and multi-language support
  </Card>

  <Card title="API Ready" icon="code">
    Instantly becomes a REST API endpoint with code examples
  </Card>
</CardGroup>

## Creating Custom Templates

### Template Builder

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

<CardGroup cols={2}>
  <Card title="Visual Editor" icon="eye">
    Point-and-click field creation with live preview
  </Card>

  <Card title="AI Suggestions" icon="sparkles">
    Smart field recommendations based on your content
  </Card>

  <Card title="Real-time Testing" icon="play">
    See results as you build with confidence scoring
  </Card>

  <Card title="Version Control" icon="code-branch">
    Safe testing and deployment with rollback capabilities
  </Card>
</CardGroup>

### Step-by-Step Creation

<Steps>
  <Step title="Start Building">
    Click "New Extraction" from your dashboard or "Create Custom Template" from the library.
  </Step>

  <Step title="Name & Describe">
    Give it a descriptive name and category. Add tags for better organization.

    <Note>Good names: "Plant Disease Detector", "Pose Analysis Tracker", "Quality Inspector"</Note>
  </Step>

  <Step title="Define Fields">
    Add extraction fields using our comprehensive field types:

    <AccordionGroup>
      <Accordion title="Basic Fields" icon="text">
        * **String**: Labels, descriptions, classifications
        * **Number**: Measurements, counts, coordinates, scores
        * **Date**: Timestamps, monitoring dates
        * **Boolean**: Yes/no, present/absent, pass/fail
      </Accordion>

      <Accordion title="Advanced Fields" icon="list">
        * **Enum**: Predefined lists (severity levels, categories, types)
        * **Object**: Nested structures with subfields
        * **Image**: AI-generated images based on extracted context (beta)
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="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
  </Step>

  <Step title="Test & Refine">
    Upload sample images to test your template. Monitor confidence scores and adjust field descriptions as needed.
  </Step>

  <Step title="Publish Template">
    Your template starts as a **Draft**. When ready, publish it to make it available for API calls.
  </Step>
</Steps>

## Field Types

### Field Type Overview

Each field type has specific capabilities and features:

<Tabs>
  <Tab title="Basic Fields">
    **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
  </Tab>

  <Tab title="Advanced Fields">
    **Enum Fields**

    * Perfect for: Predefined lists (severity levels, categories, types)
    * Features: Validation against specific choices

    **Object Fields**

    * Perfect for: Nested structures with subfields
    * Features: Complex data relationships

    **Image Fields (Beta)**

    * Perfect for: AI-generated images based on context
    * Features: Visual content generation
    * Note: Currently in beta testing
  </Tab>

  <Tab title="Field Configuration">
    **Common Options**:

    ```json theme={null}
    {
      "name": "field_name",
      "description": "Detailed field description",
      "type": "string",
      "required": true,
      "return_as_list": false
    }
    ```

    **Object Subfields**:

    ```json theme={null}
    {
      "name": "detection_results",
      "type": "object",
      "subfields": [
        {"name": "object_type", "type": "string"},
        {"name": "confidence", "type": "number"},
        {"name": "coordinates", "type": "string"}
      ]
    }
    ```
  </Tab>
</Tabs>

## Template Versioning

### Version Lifecycle

Templates follow a structured lifecycle to ensure reliable API operations:

<CardGroup cols={3}>
  <Card title="Draft" icon="pencil">
    **Editable**: Freely modify fields, descriptions, and settings
    **Testing**: Upload images to test extraction quality
    **Private**: Not available for API calls until published
  </Card>

  <Card title="Published" icon="check">
    **Immutable**: Cannot be modified directly
    **Live**: Available for API extractions
    **Stable**: Guaranteed consistent behavior for integrations
  </Card>

  <Card title="Archived" icon="folder">
    **Preserved**: Maintains history but not actively used
    **Reference**: Available for rollback if needed
    **Inactive**: No longer receives API traffic
  </Card>
</CardGroup>

### Versioning Behavior

<AccordionGroup>
  <Accordion title="Automatic Draft Creation" icon="sparkles">
    **Smart Versioning**: When you edit a published template, the system automatically creates a new draft version

    **Benefits**:

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

    **Workflow**:

    1. Click "Edit" on published template
    2. System creates new draft version automatically
    3. Make your changes in the draft
    4. Test thoroughly before publishing
  </Accordion>

  <Accordion title="Version Control" icon="code-branch">
    **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
  </Accordion>

  <Accordion title="API Version Control" icon="code">
    **Version-Specific Calls**: Specify exact versions for production stability

    **Default Behavior**: Uses latest published version if no version specified

    **Production Tip**: Always specify version numbers in production to avoid unexpected changes
  </Accordion>
</AccordionGroup>

### Version Management Workflow

<Steps>
  <Step title="Create Initial Version">
    New templates start as Draft v1. Define fields, test, and publish when ready.
  </Step>

  <Step title="Make Changes">
    Edit published templates automatically creates new draft versions. Original remains live.
  </Step>

  <Step title="Test Changes">
    Use draft version for testing. Previous published version continues serving API calls.
  </Step>

  <Step title="Publish Update">
    Publishing draft makes it live and archives the previous version.
  </Step>

  <Step title="Monitor & Rollback">
    Monitor performance. Can instantly rollback to previous versions if needed.
  </Step>
</Steps>

## Template Performance

### Key Metrics to Monitor

<AccordionGroup>
  <Accordion title="Success Rate" icon="chart-bar">
    **Target**: Above `90%` for reliable templates

    **Optimization Strategies**:

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

  <Accordion title="Processing Time" icon="clock">
    **Typical Range**: 1-3 seconds per extraction

    **Factors Affecting Speed**:

    * Image size and complexity
    * Number of fields
    * Field type complexity
    * Batch size for multiple images
  </Accordion>
</AccordionGroup>

### Performance Optimization

<CardGroup cols={2}>
  <Card title="Better Descriptions" icon="pencil">
    **Detailed field descriptions** lead to `20-30%` better extraction accuracy
  </Card>

  <Card title="Quality Images" icon="image">
    **High-resolution, clear images** improve confidence scores significantly
  </Card>

  <Card title="Field Optimization" icon="gear">
    **Use appropriate field types** that match your data requirements
  </Card>
</CardGroup>

## Advanced Features

### Conditional Fields

Extract fields only when certain conditions are met:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Extraction Quality Issues" icon="chart-line-down">
    **Problem**: AI extractions are not accurate or reliable

    **Solutions**:

    * **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**:

    ```json theme={null}
    // 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"}
    ```
  </Accordion>

  <Accordion title="Inconsistent Results" icon="shuffle">
    **Problem**: Same image gives different results across API calls

    **Solutions**:

    * **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**:

    ```javascript theme={null}
    // Always specify version in production
    {
      "template_id": "pose-analyzer",
      "version_number": 2,  // Pin to specific version
      "image_url": "..."
    }
    ```
  </Accordion>

  <Accordion title="Version Management Issues" icon="code-branch">
    **Problem**: Confusion about draft vs published versions

    **Understanding 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
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Start Simple" icon="seedling">
    Begin with 3-5 core fields using basic types, then add complexity incrementally
  </Card>

  <Card title="Test Thoroughly" icon="microscope">
    Use diverse, real-world images representing edge cases before publishing
  </Card>

  <Card title="Version Control" icon="code-branch">
    Always test new versions thoroughly and pin versions in production
  </Card>
</CardGroup>

### Template Design Guidelines

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

## What's Next?

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Dive deep into all available endpoints and options
  </Card>

  <Card title="Integration Examples" icon="puzzle-piece" href="/development">
    See real-world implementation patterns and best practices
  </Card>

  <Card title="Dashboard Guide" icon="gauge" href="/essentials/dashboard">
    Master your dashboard features and template management
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@vizapi.ai">
    Get help from our expert team
  </Card>
</CardGroup>

***

<Note>
  **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!
</Note>