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

# Extract Values

> Extracts values from an image using a template

The `/agents/extract-values` endpoint extracts structured data from an image based on a provided template.

## Request

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField body="template_id" type="string">
  The ID of an existing template to use for extraction. Required for template-based extraction.
</ParamField>

<ParamField body="version_number" type="number">
  Optional version number of the template to use. If not provided or set to 0, the latest version will be used. If provided along with `template_id`, access will be verified.
</ParamField>

<ParamField body="image_url" type="string" required>
  The URL of the image to extract data from. The URL must be publicly accessible.

  **Supported formats**: PNG, JPEG, GIF, WebP, TIFF, BMP, ICO, SVG, EPS, TGA\
  **Maximum file size**: 10MB

  Alternatively, you can provide a base64-encoded image using the data URL format:

  ```
  data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMC...
  ```

  See our [Base64 Encoding Guide](/api-reference/templates/base64-encoding) for code snippets in various programming languages.
</ParamField>

<ParamField body="advanced" type="object">
  Advanced options for extraction.

  <Expandable title="Advanced options structure">
    <ParamField name="target_language" type="string">
      Optional target language for the extraction results. If provided, values will be extracted in this language.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="extracted_template_values" type="array">
  An array of fields with extracted values.

  <Expandable title="Extracted field structure">
    <ResponseField name="name" type="string">
      The name of the field.
    </ResponseField>

    <ResponseField name="description" type="string">
      A description of the field.
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Whether the field is required.
    </ResponseField>

    <ResponseField name="type" type="string">
      The data type of the field. Possible values include: "string", "number", "date", "object", "boolean", "enum".
    </ResponseField>

    <ResponseField name="subfields" type="array">
      Nested fields for complex data structures. Each subfield follows the same structure as a top-level field.
    </ResponseField>

    <ResponseField name="return_as_list" type="boolean">
      Whether the field is returned as a list. Set to true for fields that contain multiple items (like multiple objects detected in an image).
    </ResponseField>

    <ResponseField name="enum_values" type="array">
      Possible values for enum fields. Used when the field should only contain specific values.
    </ResponseField>

    <ResponseField name="value" type="any">
      The extracted value for the field. The type of this value will match the specified field type.
      For fields with return\_as\_list=true, this will be an array of values.
      For fields of type "object" with subfields, this will be an object with keys matching the subfield names.
      For image fields, this will be the URL of the generated image.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if field processing failed (especially relevant for image generation). This field is only present when there was an error processing the specific field.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Example Request with Image URL

<CodeGroup>
  ```bash cURL (Latest Version) theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/extract-values \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "template_id": "template_12345",
      "image_url": "https://example.com/plant-leaf.jpg",
      "advanced": {
        "target_language": "Spanish"
      }
    }'
  ```

  ```bash cURL (Specific Version) theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/extract-values \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "template_id": "template_12345",
      "version_number": 1,
      "image_url": "https://example.com/plant-leaf.jpg",
      "advanced": {
        "target_language": "Spanish"
      }
    }'
  ```

  ```javascript Node.js (Latest Version) theme={null}
  const fetch = require('node-fetch');

  async function extractValuesLatest() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/extract-values', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template_id: 'template_12345',
        image_url: 'https://example.com/plant-leaf.jpg',
        advanced: {
          target_language: 'Spanish'
        }
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  extractValuesLatest();
  ```

  ```javascript Node.js (Specific Version) theme={null}
  const fetch = require('node-fetch');

  async function extractValuesSpecific() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/extract-values', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template_id: 'template_12345',
        version_number: 1,
        image_url: 'https://example.com/plant-leaf.jpg',
        advanced: {
          target_language: 'Spanish'
        }
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  extractValuesSpecific();
  ```

  ```python Python (Latest Version) theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/extract-values"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "template_id": "template_12345",
      "image_url": "https://example.com/plant-leaf.jpg",
      "advanced": {
          "target_language": "Spanish"
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```

  ```python Python (Specific Version) theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/extract-values"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "template_id": "template_12345",
      "version_number": 1,
      "image_url": "https://example.com/plant-leaf.jpg",
      "advanced": {
          "target_language": "Spanish"
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Request with Base64 Encoded Image

```javascript theme={null}
const fetch = require('node-fetch');
const fs = require('fs');

// Read and encode the image
const imagePath = 'path/to/your/image.jpg';
const imageBuffer = fs.readFileSync(imagePath);
const base64Image = imageBuffer.toString('base64');

// Create a data URL
const dataUrl = `data:image/jpeg;base64,${base64Image}`;

// Call the API
async function extractValues() {
  const response = await fetch('https://api.vizapi.ai/v1/agents/extract-values', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: 'template_12345',
      // version_number: 1,  // Optional - omit to use latest version
      image_url: dataUrl,
      advanced: {
        target_language: 'Spanish'
      }
    })
  });
  
  const data = await response.json();
  console.log(data);
}

extractValues();
```

### Example Response

```json theme={null}
{
  "extracted_template_values": [
    {
      "name": "plant_species",
      "description": "The species of plant being analyzed.",
      "required": true,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": "Tomato (Solanum lycopersicum)"
    },
    {
      "name": "disease_detected",
      "description": "Whether disease is present in the plant.",
      "required": true,
      "type": "boolean",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": true
    },
    {
      "name": "disease_type",
      "description": "The type of disease detected.",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": "Blight"
    },
    {
      "name": "severity_level",
      "description": "The severity level of the detected disease.",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": ["mild", "moderate", "severe"],
      "value": "moderate"
    },
    {
      "name": "affected_area_percentage",
      "description": "Percentage of plant area affected by disease.",
      "required": false,
      "type": "number",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": 25.5
    },
    {
      "name": "treatment_recommendations",
      "description": "Recommended treatments for the detected disease.",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": true,
      "enum_values": [],
      "value": [
        "Apply copper-based fungicide",
        "Remove affected leaves",
        "Improve air circulation"
      ]
    },
    {
      "name": "analysis_visualization",
      "description": "Generated visualization showing disease analysis results",
      "required": false,
      "type": "image",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": "https://storage.vizapi.ai/generated/analysis-viz-abc123.jpg"
    }
  ]
}
```

## Error Codes

| Status Code | Description                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request - The request was malformed, missing required parameters, unsupported image format, or image exceeds 10MB limit |
| 401         | Unauthorized - Invalid or missing API key                                                                                   |
| 402         | Payment Required - Insufficient credits to perform the extraction                                                           |
| 403         | Forbidden - Access denied to the specified template                                                                         |
| 404         | Not Found - The specified template\_id was not found, or the specified version\_number does not exist                       |
| 500         | Internal Server Error - An unexpected error occurred on our servers                                                         |