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

import requests

url = "https://api.vizapi.ai/v1/agents/extract-values"

payload = {
    "template_id": "<string>",
    "version_number": 123,
    "image_url": "<string>",
    "advanced": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_id: '<string>',
    version_number: 123,
    image_url: '<string>',
    advanced: {}
  })
};

fetch('https://api.vizapi.ai/v1/agents/extract-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vizapi.ai/v1/agents/extract-values",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'template_id' => '<string>',
    'version_number' => 123,
    'image_url' => '<string>',
    'advanced' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vizapi.ai/v1/agents/extract-values"

	payload := strings.NewReader("{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vizapi.ai/v1/agents/extract-values")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vizapi.ai/v1/agents/extract-values")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "extracted_template_values": [
    {
      "name": "<string>",
      "description": "<string>",
      "required": true,
      "type": "<string>",
      "subfields": [
        {}
      ],
      "return_as_list": true,
      "enum_values": [
        {}
      ],
      "value": "<any>",
      "error": "<string>"
    }
  ]
}

POST

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

import requests

url = "https://api.vizapi.ai/v1/agents/extract-values"

payload = {
    "template_id": "<string>",
    "version_number": 123,
    "image_url": "<string>",
    "advanced": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_id: '<string>',
    version_number: 123,
    image_url: '<string>',
    advanced: {}
  })
};

fetch('https://api.vizapi.ai/v1/agents/extract-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vizapi.ai/v1/agents/extract-values",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'template_id' => '<string>',
    'version_number' => 123,
    'image_url' => '<string>',
    'advanced' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vizapi.ai/v1/agents/extract-values"

	payload := strings.NewReader("{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vizapi.ai/v1/agents/extract-values")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vizapi.ai/v1/agents/extract-values")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"template_id\": \"<string>\",\n  \"version_number\": 123,\n  \"image_url\": \"<string>\",\n  \"advanced\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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.

Show Advanced options structure

Response

extracted_template_values

array

An array of fields with extracted values.

Show Extracted field structure

name

string

The name of the field.

description

string

A description of the field.

required

boolean

Whether the field is required.

type

string

The data type of the field. Possible values include: “string”, “number”, “date”, “object”, “boolean”, “enum”.

subfields

array

Nested fields for complex data structures. Each subfield follows the same structure as a top-level field.

return_as_list

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

enum_values

array

Possible values for enum fields. Used when the field should only contain specific values.

value

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.

error

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.

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

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

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();

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();

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)

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)

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

Suggest Fields Health Check

​Request

​Response

​Examples

​Example Request with Image URL

​Example Request with Base64 Encoded Image

​Example Response

​Error Codes

Request

Response

Examples

Example Request with Image URL

Example Request with Base64 Encoded Image

Example Response

Error Codes