POST
/
v1
/
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
}'
{
  "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.
​
metadata
object
Template metadata including title, description, category, and tags. Only present when with_metadata is set to true.

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

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

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

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

​
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 CodeDescription
400Bad Request - The request was malformed, missing required parameters, unsupported image format, or image exceeds 10MB limit
401Unauthorized - Invalid or missing API key
500Internal Server Error - An unexpected error occurred on our servers