OpenAI ChatCompletion

OpenAI ChatCompletion

Certified

Send prompts to OpenAI Chat Completions

Calls the OpenAI Chat Completions API docs with a prompt or message list, optional tool calls, and optional JSON Schema structured output. Requires either prompt or messages; defaults to OpenAI sampling limits and records token usage metrics.

yaml
type: io.kestra.plugin.openai.ChatCompletion

Based on a prompt input, generate a completion response and pass it to a downstream task.

yaml
id: openai_chat
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: What is data orchestration?

tasks:
  - id: completion
    type: io.kestra.plugin.openai.ChatCompletion
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4o
    prompt: "{{ inputs.prompt }}"

  - id: log_output
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.completion.choices[0].message.content }}"

Send a prompt to OpenAI's ChatCompletion API.

yaml
id: openai_chat
namespace: company.team

tasks:
  - id: prompt
    type: io.kestra.plugin.openai.ChatCompletion
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4o
    prompt: Explain in one sentence why data engineers build data pipelines

  - id: use_output
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.prompt.choices | jq('.[].message.content') | first }}"

Based on a prompt input, ask OpenAI to call a function that determines whether you need to respond to a customer's review immediately or wait until later, and then comes up with a suggested response.

yaml
id: openai_chat
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: I love your product and would purchase it again!

tasks:
  - id: prioritize_response
    type: io.kestra.plugin.openai.ChatCompletion
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4o
    messages:
      - role: user
        content: "{{ inputs.prompt }}"
    functions:
      - name: respond_to_review
        description: Given the customer product review provided as input, determines how urgently a reply is required and then provides suggested response text.
        parameters:
          - name: response_urgency
            type: string
            description: How urgently this customer review needs a reply. Bad reviews
                         must be addressed immediately before anyone sees them. Good reviews can
                         wait until later.
            required: true
            enumValues:
              - reply_immediately
              - reply_later
          - name: response_text
            type: string
            description: The text to post online in response to this review.
            required: true

  - id: response_urgency
    type: io.kestra.plugin.core.debug.Return
    format: "{{ outputs.prioritize_response | jq('.choices[0].message.tool_calls[0].function.arguments | fromjson | .response_urgency') | first }}"

  - id: response_text
    type: io.kestra.plugin.core.debug.Return
    format: "{{ outputs.prioritize_response | jq('.choices[0].message.tool_calls[0].function.arguments | fromjson | .response_text') | first }}"
Properties

OpenAI API key

Model ID

Required OpenAI model identifier (e.g., gpt-4o); see the model docs.

Default10

The maximum number of seconds to wait for a response

Frequency penalty (-2 to 2)

Default 0; positive values reduce reuse of frequent tokens.

Defaultauto

Tool choice directive

Use 'auto' (default), 'none', or a specific function name present in functions; other names raise an error.

Functions exposed as tools

Define tool-callable functions with names, descriptions, and parameters; ignored if none provided.

Definitions
descriptionstring

Function description

namestring

Function name

parametersarray

Function parameters

description*Requiredstring

Function parameter description

Provide enough detail for the model to populate this argument correctly.

name*Requiredstring

Function parameter name

type*Requiredstring

Function parameter type

OpenAPI data type: string, number, integer, boolean, array, or object

enumValuesarray
SubTypestring

Allowed enum values

Optional; constrains the model to this fixed set for classification-like prompts.

requiredbooleanstring

Parameter required flag

Defaults to false; when true the model must provide this parameter.

JSON response schema

Stringified JSON Schema enabling response_format = json_schema; uses name kestra_schema with strict true.

Token logit bias

Map token IDs to bias values; empty when unset.

Max completion tokens

Leave null to rely on model defaults; counts only completion tokens.

Messages to send to the model

Required when prompt is absent; each entry keeps its role and content.

Definitions
contentstring
namestring
rolestring
Default1

Number of choices

Default 1; controls size of choices list.

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

Presence penalty (-2 to 2)

Default 0; positive values discourage repeating earlier topics.

Prompt text to send

Sent as a user message when messages are omitted; required if messages is not set.

Enable prompt caching

When true, enables OpenAI prompt caching to reduce latency and cost for repeated prefixes. See the prompt caching docs.

SubTypestring

Stop sequences

Up to 4 strings; default is none.

Default1.0

Sampling temperature (0–2)

Default 1.0; higher values increase randomness.

Nucleus sampling top_p

Lower values limit token candidates. Omit to let OpenAI apply its server-side default. Must be omitted for reasoning models (e.g., gpt-5.2+, gpt-5.4) which reject top_p.

A unique identifier representing your end-user

Completion choices

All choices returned by the API in order.

Definitions
index
logprobs
message

Chat completion ID

Model used

Returned object type

Expected value is chat.completion.

Token usage summary

Prompt, completion, and total token counts when provided by the API.

Definitions

More Plugins in this Category

Weaviate
Weaviate

Tasks that manage and query vectors in Weaviate.

DataAI

4 tasks

2 blueprints

Timefold
Timefold

Timefold plugin for Kestra

DataAI

2 tasks