Suggest Fields

curl --request POST \
  --url https://api.vizapi.ai/v1/agents/suggest-fields \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "image_url": "<string>",
  "text_description": "<string>",
  "with_metadata": true
}
'

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"

payload = {
    "image_url": "<string>",
    "text_description": "<string>",
    "with_metadata": True
}
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({image_url: '<string>', text_description: '<string>', with_metadata: true})
};

fetch('https://api.vizapi.ai/v1/agents/suggest-fields', 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/suggest-fields",
  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([
    'image_url' => '<string>',
    'text_description' => '<string>',
    'with_metadata' => true
  ]),
  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/suggest-fields"

	payload := strings.NewReader("{\n  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\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/suggest-fields")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\n}"

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

{
  "template_name": "<string>",
  "template": [
    {
      "name": "<string>",
      "description": "<string>",
      "required": true,
      "type": "<string>",
      "subfields": [
        {}
      ],
      "return_as_list": true,
      "enum_values": [
        {}
      ],
      "value": "<any>",
      "include_extraction_output": true,
      "enable_reference_image": true,
      "reference_image_url": "<string>"
    }
  ],
  "metadata": {
    "title": "<string>",
    "description": "<string>",
    "category": "<string>",
    "tags": [
      {}
    ]
  }
}

POST

agents

suggest-fields

Suggest Fields

curl --request POST \
  --url https://api.vizapi.ai/v1/agents/suggest-fields \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "image_url": "<string>",
  "text_description": "<string>",
  "with_metadata": true
}
'

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"

payload = {
    "image_url": "<string>",
    "text_description": "<string>",
    "with_metadata": True
}
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({image_url: '<string>', text_description: '<string>', with_metadata: true})
};

fetch('https://api.vizapi.ai/v1/agents/suggest-fields', 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/suggest-fields",
  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([
    'image_url' => '<string>',
    'text_description' => '<string>',
    'with_metadata' => true
  ]),
  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/suggest-fields"

	payload := strings.NewReader("{\n  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\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/suggest-fields")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"image_url\": \"<string>\",\n  \"text_description\": \"<string>\",\n  \"with_metadata\": true\n}"

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

{
  "template_name": "<string>",
  "template": [
    {
      "name": "<string>",
      "description": "<string>",
      "required": true,
      "type": "<string>",
      "subfields": [
        {}
      ],
      "return_as_list": true,
      "enum_values": [
        {}
      ],
      "value": "<any>",
      "include_extraction_output": true,
      "enable_reference_image": true,
      "reference_image_url": "<string>"
    }
  ],
  "metadata": {
    "title": "<string>",
    "description": "<string>",
    "category": "<string>",
    "tags": [
      {}
    ]
  }
}

The /agents/suggest-fields endpoint analyzes an image and/or text description and suggests appropriate fields for extraction based on the provided content.

Request

x-api-key

string

required

Your API key for authentication.

image_url

string

The URL of the image to analyze. The URL must be publicly accessible.Supported formats: PNG, JPEG, GIF, WebP, TIFF, BMP, ICO, SVG, EPS, TGA
Maximum file size: 10MB

text_description

string

A text description of the data you want to extract. For example, “Plant disease detection with severity levels and affected area percentage.”

with_metadata

boolean

Whether to include metadata generation (title, description, category, tags) in addition to fields. Defaults to false.When set to true, the response will include a metadata object with comprehensive template information that can be used for template creation and organization.

At least one of image_url or text_description must be provided. For best results, provide both.

Response

template_name

string

A suggested name for the template based on the image content.

template

array

An array of suggested fields for extraction.

Show Template 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”.

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 should be 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 (null in the suggest-fields response). This field is included for consistency with the extract-values response.

include_extraction_output

boolean

For image fields: whether to include other extracted field values as context for image generation.

enable_reference_image

boolean

For image fields: whether reference image upload is enabled.

reference_image_url

string

For image fields: URL of the reference image to guide generation.

metadata

object

Template metadata including title, description, category, and tags. Only present when with_metadata is set to true.

Show Metadata structure

title

string

A descriptive title for the extraction template.

description

string

A detailed description of what this template extracts.

Examples

Example Request with Image URL

curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/plant-leaf.jpg"
  }'

const fetch = require('node-fetch');

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

suggestFields();

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "image_url": "https://example.com/plant-leaf.jpg"
}

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

Example Request with Text Description

curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
  }'

const fetch = require('node-fetch');

async function suggestFields() {
  const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations'
    })
  });
  
  const data = await response.json();
  console.log(data);
}

suggestFields();

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
}

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

Example Request with Both Inputs

curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/plant-leaf.jpg",
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
  }'

const fetch = require('node-fetch');

async function suggestFields() {
  const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      image_url: 'https://example.com/plant-leaf.jpg',
      text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations'
    })
  });
  
  const data = await response.json();
  console.log(data);
}

suggestFields();

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "image_url": "https://example.com/plant-leaf.jpg",
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
}

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

Example Request with Metadata Generation

curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/plant-leaf.jpg",
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations",
    "with_metadata": true
  }'

const fetch = require('node-fetch');

async function suggestFieldsWithMetadata() {
  const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      image_url: 'https://example.com/plant-leaf.jpg',
      text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations',
      with_metadata: true
    })
  });
  
  const data = await response.json();
  console.log(data);
}

suggestFieldsWithMetadata();

import requests

url = "https://api.vizapi.ai/v1/agents/suggest-fields"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "image_url": "https://example.com/plant-leaf.jpg",
    "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations",
    "with_metadata": True
}

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

Example Response (without metadata)

{
  "template_name": "Plant Disease Detector",
  "template": [
    {
      "name": "plant_species",
      "description": "The species of plant being analyzed",
      "required": true,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_detected",
      "description": "Whether disease is present in the plant",
      "required": true,
      "type": "boolean",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_type",
      "description": "The type of disease detected",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "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": null
    },
    {
      "name": "affected_area_percentage",
      "description": "Percentage of plant area affected by disease",
      "required": false,
      "type": "number",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "treatment_recommendations",
      "description": "Recommended treatments for the detected disease",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": true,
      "enum_values": [],
      "value": null
    }
  ]
}

Example Response (with metadata)

{
  "template_name": "Plant Disease Analysis System",
  "template": [
    {
      "name": "plant_species",
      "description": "The species of plant being analyzed",
      "required": true,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_detected",
      "description": "Whether disease is present in the plant",
      "required": true,
      "type": "boolean",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "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": null
    }
  ],
  "metadata": {
    "title": "Advanced Plant Disease Analysis System",
    "description": "Comprehensive plant health assessment including disease detection, severity classification, and treatment recommendations for agricultural and horticultural applications.",
    "category": "Agriculture",
    "tags": ["plant-health", "disease-detection", "agriculture", "crop-monitoring", "precision-farming"]
  }
}

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
500	Internal Server Error - An unexpected error occurred on our servers

Get User Templates Extract Values

​Request

​Response

​Examples

​Example Request with Image URL

​Example Request with Text Description

​Example Request with Both Inputs

​Example Request with Metadata Generation

​Example Response (without metadata)

​Example Response (with metadata)

​Error Codes

Request

Response

Examples

Example Request with Image URL

Example Request with Text Description

Example Request with Both Inputs

Example Request with Metadata Generation

Example Response (without metadata)

Example Response (with metadata)

Error Codes