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

string

required

Your API key for authentication.

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

string

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

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

string

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

array

An array of suggested fields for extraction.

Show Template field structure

string

The name of the field.

string

A description of the field.

boolean

Whether the field is required.

string

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

array

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

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

array

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

any

The extracted value (null in the suggest-fields response). This field is included for consistency with the extract-values response.

boolean

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

boolean

For image fields: whether reference image upload is enabled.

string

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

object

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

Show Metadata structure

string

A descriptive title for the extraction template.

string

A detailed description of what this template extracts.

string

The category this template belongs to (e.g., ‘Agriculture’, ‘Medical Imaging’, ‘Quality Control’, etc.).

array

A list of relevant tags for this template.

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

API Documentation

Templates

Agents

Utility

Suggest Fields

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

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