Form Generation

Overview

The Form Generation endpoint analyzes an uploaded form document and extracts its complete structure, identifying all fillable fields, labels, field types, and layout. It returns a structured JSON representation of the form with all fields ready for data population.

Use this endpoint to:

Extract form structure from PDF and document files
Identify all fillable fields, labels, and field types
Detect field options for dropdowns and multi-select fields
Prepare forms for automated filling
Build form processing and automation workflows

Endpoint Details

Method: POST
Endpoint: /api/agent/form/generate
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI
Content-Type	string	Yes	Must be application/json

Request Body

{
    "doc_process_id": "ad9c5a6e66889e24c4a745b9d867c2fe",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Body Fields

Field	Type	Required	Description
doc_process_id	string	Yes	Form document ID to extract structure from (obtained from Upload or List Documents APIs)
model_data	object	Yes	AI model configuration
model_data.model_name	string	Yes	AI model to use for form extraction (see supported models below)
model_data.api_key	string	No	Your own LLM API key (leave empty to use platform's default keys)

Supported AI Models

Model Name	Provider
gpt-5.1	OpenAI
gpt-5-mini	OpenAI
claude-sonnet-4-5-20250929	Anthropic
gemini/gemini-2.5-flash-lite	Google
gemini/gemini-2.5-pro	Google
gemini/gemini-3-pro-preview	Google
mistral/mistral-small-latest	Mistral AI
mistral/mistral-medium-latest	Mistral AI
llama3.1-70b	Meta

Using Your Own LLM API Keys

Platform Keys (Default)

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Your Own Keys

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": "sk-your-openai-api-key-here"
    }
}

Response Specification

Success Response (200 OK)

{
    "data": {
        "document_id": "Sample_Form.pdf",
        "form_template": [
            {
                "label": "Given Name",
                "type": "text",
                "example": null,
                "options": null,
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            },
            {
                "label": "Driving License",
                "type": "select",
                "example": null,
                "options": [
                    "Yes",
                    "No"
                ],
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            },
            {
                "label": "I speak and understand",
                "type": "multiselect",
                "example": null,
                "options": [
                    "Deutsch",
                    "English",
                    "Français",
                    "Esperanto",
                    "Latin"
                ],
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            }
        ]
    },
    "message": "Form created successfully"
}

Response Fields

Field	Type	Description
data	object	Response data object
data.document_id	string	Original form document filename
data.form_template	array	Array of form field objects
data.form_template[].label	string	Field label/name as it appears on the form
data.form_template[].type	string	Field type: text, number, select, multiselect, date, etc.
data.form_template[].example	string/null	Example value for the field (if available)
data.form_template[].options	array/null	Available options for select or multiselect fields, null for other types
data.form_template[].user_value	object	User value object (empty in generation, filled during form filling)
data.form_template[].user_value.source	string/null	Source document for the value (null in generation)
data.form_template[].user_value.possible_value	any/null	Extracted value (null in generation)
message	string	Human-readable response message

Understanding user_value Structure

In the Form Generation response, user_value is always empty:

{
    "user_value": {
        "source": null,        // Will be filled during Form Filling
        "possible_value": null // Will be filled during Form Filling
    }
}

This structure will be populated when using the Form Filling API.

Error Responses

401 Unauthorized

{
    "data": {},
    "message": "Invalid or missing access key"
}

Cause: Missing or invalid access-key header.

422 Unprocessable Entity - Invalid Model Name

{
    "detail": [
        {
            "type": "literal_error",
            "loc": [
                "body",
                "model_data",
                "model_name"
            ],
            "msg": "Input should be 'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'",
            "input": "",
            "ctx": {
                "expected": "'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'"
            }
        }
    ]
}

Cause: Invalid or unsupported model_name in model_data. See supported models list above.

400 Bad Request - Invalid Document IDs

{
    "data": {},
    "message": "Invalid docs selected"
}

Causes:

Missing or invalid doc_process_ids.

500 Internal Server Error - Invalid LLM API Key

{
    "data": {},
    "message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}

Cause: The api_key provided in model_data is invalid or expired. Verify your LLM provider API key.

500 Internal Server Error - General Error

{
    "data": {},
    "message": "Something went wrong"
}

Causes:

LLM service temporarily unavailable
Server-side processing error

Code Snippets

curl --location 'https://api.k-v.ai/api/agent/form/generate' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "doc_process_id": "ad9c5a6e66889e24c4a745b9d867c2fe",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}'

import requests
import json

url = "https://api.k-v.ai/api/agent/form/generate"

payload = json.dumps({
    "doc_process_id": "ad9c5a6e66889e24c4a745b9d867c2fe",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
})

headers = {
    'access-key': 'YOUR_ACCESS_KEY',
    'Content-Type': 'application/json'
}

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

print(response.text)

const axios = require('axios');

let data = JSON.stringify({
    "doc_process_id": "ad9c5a6e66889e24c4a745b9d867c2fe",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
});

let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.k-v.ai/api/agent/form/generate',
    headers: { 
        'access-key': 'YOUR_ACCESS_KEY',
        'Content-Type': 'application/json'
    },
    data: data
};

axios.request(config)
.then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
    console.log(error);
});

Important Notes

Document Processing: Only extract form structure from documents with status: "processed" from List Documents API
Field Detection: The AI automatically identifies all fillable fields
Empty user_value: In the generation response, user_value.source and user_value.possible_value are always null
Preserve Structure: Save the complete form structure for use with the Form Filling API

Next Steps

After generating form structure:

Review Fields: Examine all extracted fields and their types
Save Structure: Store the form template JSON for reuse
Prepare Source Documents: Upload documents containing data to fill the form
Fill Form: Use the Form Filling API with the form structure and source documents

Need Help? Contact support at support@k-v.ai

Form Generation

On this page