POST
/
v1
/
agents
/
extract-values
Extract Values
curl --request POST \
  --url https://api.vizapi.ai/v1/agents/extract-values \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "template_id": "<string>",
  "version_number": 123,
  "image_url": "<string>",
  "advanced": {}
}'
{
  "extracted_template_values": [
    {
      "name": "<string>",
      "description": "<string>",
      "required": true,
      "type": "<string>",
      "subfields": [
        {}
      ],
      "return_as_list": true,
      "enum_values": [
        {}
      ],
      "value": "<any>",
      "error": "<string>"
    }
  ]
}
The /agents/extract-values endpoint extracts structured data from an image based on a provided template.

​
Request

​
x-api-key
string
required
Your API key for authentication.
​
template_id
string
The ID of an existing template to use for extraction. Required for template-based extraction.
​
version_number
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.
​
image_url
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: 10MBAlternatively, you can provide a base64-encoded image using the data URL format:
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMC...
See our Base64 Encoding Guide for code snippets in various programming languages.
​
advanced
object
Advanced options for extraction.

​
Response

​
extracted_template_values
array
An array of fields with extracted values.

​
Examples

​
Example Request with Image URL

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"
    }
  }'

​
Example Request with Base64 Encoded Image

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

{
  "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 CodeDescription
400Bad Request - The request was malformed, missing required parameters, unsupported image format, or image exceeds 10MB limit
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient credits to perform the extraction
403Forbidden - Access denied to the specified template
404Not Found - The specified template_id was not found, or the specified version_number does not exist
500Internal Server Error - An unexpected error occurred on our servers