AI JSONStructuredExtraction

AI JSONStructuredExtraction

Certified

Extract JSON fields from text

Builds a JSON schema from jsonFields (all required) and asks the model to return compliant JSON for the given input (prompt or contentBlocks). Requires a provider that supports JSON response formats; otherwise include schema hints in the prompt. Returns extracted JSON, token usage, and finish reason.

yaml
type: io.kestra.plugin.ai.completion.JSONStructuredExtraction

Extract person fields (Gemini)

yaml
id: json_structured_extraction
namespace: company.ai

tasks:
  - id: extract_person
    type: io.kestra.plugin.ai.completion.JSONStructuredExtraction
    schemaName: Person
    jsonFields:
      - name
      - city
      - country
      - email
    prompt: |
      From the text below, extract the person's name, city, and email.
      If a field is missing, leave it blank.

      Text:
      "Hi! I'm John Smith from Paris, France. You can reach me at john.smith@example.com."
    systemMessage: You extract structured data in JSON format.
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-2.5-flash

Extract order details (OpenAI)

yaml
id: json_structured_extraction_order
namespace: company.ai

tasks:
  - id: extract_order
    type: io.kestra.plugin.ai.completion.JSONStructuredExtraction
    schemaName: Order
    jsonFields:
      - order_id
      - customer_name
      - city
      - total_amount
    prompt: |
      Extract the order_id, customer_name, city, and total_amount from the message.
      For the total amount, keep only the number without the currency symbol.
      Return only JSON with the requested keys.

      Message:
      "Order #A-1043 for Jane Doe, shipped to Berlin. Total: 249.99 EUR."
    systemMessage: You are a precise JSON data extraction assistant.
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    guardrails:
      input:
        - expression: "{{ message.length < 10000 }}"
          message: "Message too long"
      output:
        - expression: "{{ not (response contains 'CONFIDENTIAL') }}"
          message: "Response contains confidential information"
Properties
SubTypestring

JSON Fields

List of fields to extract from the text

Language Model Provider

Definitions

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
accessKeyId*Requiredstring

AWS Access Key ID

modelName*Requiredstring

Model name

secretAccessKey*Requiredstring

AWS Secret Access Key

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

modelTypestring
DefaultCOHERE
Possible Values
COHERETITAN

Amazon Bedrock Embedding Model Type

Provides Claude chat models only; embeddings and images are unsupported. Enforces Anthropic rules (no seed/responseFormat). Thinking mode requires max_tokens > thinking.budget_tokens; set API key and optional base URL.

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

maxTokensintegerstring

Maximum Tokens

Specifies the maximum number of tokens that the model is allowed to generate in its response.

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
endpoint*Requiredstring

API endpoint

The Azure OpenAI endpoint in the format: https://{resource}.openai.azure.com/

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI
apiKeystring

API Key

baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientIdstring

Client ID

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

clientSecretstring

Client secret

serviceVersionstring

API version

tenantIdstring

Tenant ID

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
baseUrlstring
Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

If you use a model in the China (Beijing) region, you need to replace the URL with: https://dashscope.aliyuncs.com/api/v1,
otherwise use the Singapore region of: "https://dashscope-intl.aliyuncs.com/api/v1.
The default value is computed based on the system timezone.
caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

enableSearchbooleanstring

Whether the model uses Internet search results for reference when generating text or not

maxTokensintegerstring

The maximum number of tokens returned by this request

repetitionPenaltynumberstring

Repetition in a continuous sequence during model generation

Increasing repetition_penalty reduces the repetition in model generation,
1.0 means no penalty. Value range: (0, +inf)

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek
baseUrlstring
Defaulthttps://api.deepseek.com/v1

API base URL

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"
gitHubToken*Requiredstring

GitHub Token

Personal Access Token (PAT) used to access GitHub Models.

modelName*Requiredstring

Model name

type*Requiredobject
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Supports Gemini chat, embeddings, and images. Tools do not support JSON Schema anyOf, and tools cannot be combined with responseFormat; configure either but not both.

Thinking models (e.g. gemini-3.5-flash) attach a thought_signature to every function-call part. This provider automatically captures those signatures (returnThinking defaults to true) and re-attaches them to the conversation history for every follow-up request (sendThinking is always enabled), preventing the 400 INVALID_ARGUMENT – Function call is missing a thought_signature error.

In addition, thinking is disabled by default (thinkingBudget = 0) to reduce token usage, unless thinkingEnabled: true or thinkingBudgetTokens > 0 is explicitly set.

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-2.5-flash
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-2.5-flash
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini
apiKeystring

API Key

Required unless certificate-based authentication is configured with clientPem (optionally with caPem).

baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

embeddingModelConfiguration

The configuration for embeddingModel

maxRetriesintegerstring

Maximum number of retries for failed requests

outputDimensionalityintegerstring

Used to specify output embedding size

If set, output embeddings will be truncated to the size specified.

taskTypestring
Possible Values
RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Used to convey intended downstream application to help the model produce better embeddings.

timeoutstring

Timeout in seconds for each request

titleMetadataKeystring

The headline or name of the document (passed to the model as metadata).

If set, this help improving retrieval quality by providing context for a document.

Calls Vertex AI Gemini chat, embeddings, or images using project, location, and endpoint settings. Requires GCP credentials; ensure response formats are supported by the selected model/region.

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      endpoint: your-vertex-ai-endpoint
      location: your-google-cloud-region
      project: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
endpoint*Requiredstring

Endpoint URL

location*Requiredstring

Project location

modelName*Requiredstring

Model name

project*Requiredstring

Project ID

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
baseUrlstring
Defaulthttps://router.huggingface.co/v1

API base URL

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
baseUrl*Requiredstring

API base URL

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI
caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral:7b
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls Oracle Cloud GenAI chat/embedding models with compartment OCID and region. Auth is handled via OCI SDK provider (config file or instance principals). Ensure the model is permitted in the chosen compartment.

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: oracle.chat.gpt-3.5
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
compartmentId*Requiredstring

OCID of OCI Compartment with the model

modelName*Requiredstring

Model name

region*Requiredstring

OCI Region to connect the client to

type*Requiredobject
authProviderstring

OCI SDK Authentication provider

baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
endpoint*Requiredstring

Model endpoint

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI
baseUrlstring
Defaulthttps://api.openai.com/v1

API base URL

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: x-ai/grok-beta
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

projectId*Requiredstring

Project Id

type*Requiredobject
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: @cf/meta/llama-2-7b-chat-fp16
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
accountId*Requiredstring

Account Identifier

Unique identifier assigned to an account

apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
Possible Values
io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI
baseUrlstring

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"
apiKey*Requiredstring

API Key

modelName*Requiredstring

Model name

type*Requiredobject
baseUrlstring
Defaulthttps://open.bigmodel.cn/

API base URL

The base URL for ZhiPu API (defaults to https://open.bigmodel.cn/)

caPemstring

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPemstring

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

maxRetriesintegerstring

The maximum retry times to request

maxTokenintegerstring

The maximum number of tokens returned by this request

stopsarray
SubTypestring

With the stop parameter, the model will automatically stop generating text when it is about to contain the specified string or token_id

Schema Name

The name of the JSON schema for structured extraction

Default{}

Chat configuration

Definitions
logRequestsbooleanstring

Log LLM requests

If true, prompts and configuration sent to the LLM will be logged at INFO level.

logResponsesbooleanstring

Log LLM responses

If true, raw responses from the LLM will be logged at INFO level.

maxTokenintegerstring

Maximum number of tokens the model can generate in the completion (response). This limits the length of the output.

promptCachingbooleanstring

Enable Prompt Caching

When enabled, instructs the provider to cache system messages and tool definitions across requests. This can significantly reduce latency and cost for repeated calls with the same system prompt or tools. Currently supported by Anthropic only; other providers silently ignore this setting.

responseFormat

Response format

Defines the expected output format. Default is plain text. Some providers allow requesting JSON or schema-constrained outputs, but support varies and may be incompatible with tool use. When using a JSON schema, the output will be returned under the key jsonOutput.

jsonSchemaobject

JSON Schema (used when type = JSON)

Provide a JSON Schema describing the expected structure of the response. In Kestra flows, define the schema in YAML (it is still a JSON Schema object). Example (YAML): 

responseFormat: 
    type: JSON
    jsonSchema: 
      type: object
      required: ["category", "priority"]
      properties: 
        category: 
          type: string
          enum: ["ACCOUNT", "BILLING", "TECHNICAL", "GENERAL"]
        priority: 
          type: string
          enum: ["LOW", "MEDIUM", "HIGH"]

Note: Provider support for strict schema enforcement varies. If unsupported, guide the model about the expected output structure via the prompt and validate downstream.

jsonSchemaDescriptionstring

Schema description (optional)

Natural-language description of the schema to help the model produce the right fields. Example: "Classify a customer ticket into category and priority."

strictJsonbooleanstring
Defaultfalse

Enable strict JSON schema mode

When true, providers that support it enforce strict JSON schema output when type is JSON.

typestring
DefaultTEXT
Possible Values
TEXTJSON

Response format type

Specifies how the LLM should return output. Allowed values:

  • TEXT (default): free-form natural language.
  • JSON: structured output validated against a JSON Schema.
returnThinkingbooleanstring

Return Thinking

Controls whether to return the model's internal reasoning or 'thinking' text, if available. When enabled, the reasoning content is extracted from the response and made available in the AiMessage object. Does not trigger the thinking process itself—only affects whether the output is parsed and returned.

For Google Gemini: defaults to true so that thought_signature values on function-call parts are captured and automatically re-sent in subsequent requests, preventing tool-call failures on native thinking models (e.g. gemini-3.5-flash).

seedintegerstring

Seed

Optional random seed for reproducibility. Provide a positive integer (e.g., 42, 1234). Using the same seed with identical settings produces repeatable outputs.

temperaturenumberstring

Temperature

Controls randomness in generation. Typical range is 0.0–1.0. Lower values (e.g., 0.2) make outputs more focused and deterministic, while higher values (e.g., 0.7–1.0) increase creativity and variability.

thinkingBudgetTokensintegerstring

Thinking Token Budget

Specifies the maximum number of tokens allocated as a budget for internal reasoning processes, such as generating intermediate thoughts or chain-of-thought sequences, allowing the model to perform multi-step reasoning before producing the final output.

For Google Gemini: when neither this property nor thinkingEnabled is set, the budget defaults to 0 (thinking disabled) to prevent tool-call failures on native thinking models such as gemini-3.5-flash. Set this to a positive integer (e.g. 1024) to allow thinking.

thinkingEnabledbooleanstring

Enable Thinking

Enables internal reasoning ('thinking') in supported language models, allowing the model to perform intermediate reasoning steps before producing a final output; this is useful for complex tasks like multi-step problem solving or decision making, but may increase token usage and response time, and is only applicable to compatible models.

For Google Gemini: when neither this property nor thinkingBudgetTokens is set, thinking is explicitly disabled (thinkingBudget = 0) to prevent tool-call failures on native thinking models such as gemini-3.5-flash. Set thinkingEnabled: true or thinkingBudgetTokens > 0 to opt back in.

topKintegerstring

Top-K

Limits sampling to the top K most likely tokens at each step. Typical values are between 20 and 100. Smaller values reduce randomness; larger values allow more diverse outputs.

topPnumberstring

Top-P (nucleus sampling)

Selects from the smallest set of tokens whose cumulative probability is ≤ topP. Typical values are 0.8–0.95. Lower values make the output more focused, higher values increase diversity.

Content blocks

Multimodal input blocks for extraction (TEXT, IMAGE, PDF). Use either prompt or contentBlocks. For IMAGE/PDF uri, supported smart URI schemes are kestra://, file://, and nsfile://.

Definitions
textstring

Text

Text payload, required for TEXT blocks.

typestring
Possible Values
TEXTIMAGEPDF

Block type

Block type. Defaults to TEXT when omitted.

uristring

URI

URI payload for IMAGE and PDF blocks. Supported smart URI schemes: kestra://, file://, and nsfile://.

Guardrails

Input guardrails are evaluated against the prompt before the LLM is called. Output guardrails are evaluated against the extracted JSON before it is returned. The first failing rule stops execution and sets guardrailViolated to true in the output.

Definitions
inputarray

Input guardrails

Guardrails evaluated against the user message before it is sent to the LLM. Each rule's Pebble expression has access to the message variable (the user message text). The first failing rule halts execution and returns a guardrail violation in the task output.

expression*Requiredstring
Min length1

Pebble expression

A Pebble expression that must evaluate to true for the guardrail to pass. For input guardrails, the variable message contains the user message text. For output guardrails, the variable response contains the AI response text, finishReason contains the finish reason, inputTokenCount and outputTokenCount contain the respective token counts. Example: {{ message.length < 10000 }} Example: {{ not (response contains 'CONFIDENTIAL') }}

message*Requiredstring
Min length1

Violation message

The message returned when the expression evaluates to false.

outputarray

Output guardrails

Guardrails evaluated against the AI response before it is returned. Each rule's Pebble expression has access to response (the AI response text), finishReason, inputTokenCount, and outputTokenCount. The first failing rule halts and returns a guardrail violation in the task output.

expression*Requiredstring
Min length1

Pebble expression

A Pebble expression that must evaluate to true for the guardrail to pass. For input guardrails, the variable message contains the user message text. For output guardrails, the variable response contains the AI response text, finishReason contains the finish reason, inputTokenCount and outputTokenCount contain the respective token counts. Example: {{ message.length < 10000 }} Example: {{ not (response contains 'CONFIDENTIAL') }}

message*Requiredstring
Min length1

Violation message

The message returned when the expression evaluates to false.

Reference (ref) of the pluginDefaults to apply to this task.

Text prompt

Text input for structured JSON extraction. Use either prompt or contentBlocks.

DefaultYou are a structured JSON extraction assistant. Always respond with valid JSON.

System message

Optional system instruction for the model.

Extracted JSON

The structured JSON output

Possible Values
STOPLENGTHTOOL_EXECUTIONCONTENT_FILTEROTHER

Finish reason

Defaultfalse

Guardrail violated

True if a guardrail rule was violated

Guardrail violation message

The message from the first violated guardrail rule

Schema Name

The schema name used for the structured JSON extraction

Token usage

Definitions
inputTokenCountinteger
outputTokenCountinteger
totalTokenCountinteger
Unitcalls

Number of times a chat model is obtained from a provider, tagged by provider class name

Unittoken

Large Language Model (LLM) input token count

Unittoken

Large Language Model (LLM) output token count

Unittoken

Large Language Model (LLM) total token count

More Plugins in this Category

Weaviate
Weaviate

Tasks that manage and query vectors in Weaviate.

DataAI

4 tasks

2 blueprints

Mistral
Mistral

Tasks and triggers for Mistral AI: chat completions and workflow orchestration.

AI

3 tasks