---
url: /orchestration/reference/operations/InvokeChatCompletionStepTemplate.md
description: 'POST /v2/consumer/recipes/chatCompletion — ChatCompletion'
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# ChatCompletion

`POST https://orchestration.civitai.com/v2/consumer/recipes/chatCompletion`

Operation `InvokeChatCompletionStepTemplate` · Recipes · Civitai Orchestration API, generated from the published OpenAPI spec ([v2-consumers.json](https://developer.civitai.com/openapi/v2-consumers.json)); the interactive HTML page is this URL without `.md`.

Generate chat completions using language models with support for text and image inputs.
/// Compatible with OpenAI Chat Completions API format.

## Authentication

Send `Authorization: Bearer <token>` (the spec's `ApiKey` scheme); this operation documents `401 Unauthorized` for a missing or invalid token. See [Authentication](https://developer.civitai.com/orchestration/guide/authentication.md).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `experimental` | query | boolean | no |  |
| `allowMatureContent` | query | boolean | no |  |
| `whatif` | query | boolean | no |  |
| `ephemeral` | query | boolean | no |  |
| `tier` | query | `WorkflowTier` (one of `paid`, `free`) | no | How a workflow is paid for. |

## Request body

Optional. Content types: `application/json`, `text/json`, `application/*+json`.

Schema `ChatCompletionInput` — Input for a chat completion step, compatible with OpenAI Chat Completions API.

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | (minLength `1`) |
| `messages` | array of `ChatCompletionMessage` | yes | (minItems `1`) |
| `temperature` | number (double) | no | Temperature for sampling (0-2). Higher values make output more random. (default `1`, minimum `0`, maximum `2`) |
| `topP` | number (double) | no | Nucleus sampling parameter. Consider tokens with top_p probability mass. (default `1`, minimum `0`, maximum `1`) |
| `maxTokens` | integer (int32), nullable | no | (minimum `1`, maximum `128000`) |
| `thinkingTokenBudget` | integer (int32), nullable | no | vLLM reasoning-token limit per completion, including each server-tool round: 0 ends thinking immediately, -1/null sets no separate limit. MaxTokens still caps thinking plus answer tokens. (minimum `-1`, maximum `2147483647`) |
| `reasoningEffort` | string, nullable | no | OpenAI reasoning_effort: none, minimal, low, medium, high or xhigh. Portable across vLLM and hosted providers; the worker translates it to each provider's native reasoning control. (pattern `^(none\|minimal\|low\|medium\|high\|xhigh)$`) |
| `n` | integer (int32) | no | Number of completions to generate. (default `1`, minimum `1`, maximum `128`) |
| `stop` | array of string, nullable | no | Up to 4 sequences where the API will stop generating tokens. |
| `presencePenalty` | number (double) | no | Presence penalty (-2.0 to 2.0). Positive values penalize new tokens based on whether they appear in the text so far. (default `0`, minimum `-2`, maximum `2`) |
| `frequencyPenalty` | number (double) | no | Frequency penalty (-2.0 to 2.0). Positive values penalize new tokens based on their existing frequency in the text. (default `0`, minimum `-2`, maximum `2`) |
| `seed` | integer (int64), nullable | no |  |
| `user` | string, nullable | no |  |
| `logprobs` | boolean, nullable | no |  |
| `topLogprobs` | integer (int32), nullable | no | Number of top log probability candidates to return per generated token. Requires `logprobs` to be enabled. (minimum `0`, maximum `20`) |
| `chatTemplateKwargs` | object, nullable | no | Model-specific chat template options, forwarded unchanged to vLLM as chat_template_kwargs. Prefer reasoningEffort and thinkingTokenBudget for reasoning control. |
| `tools` | array of `ChatCompletionTool`, nullable | no |  |
| `tool_choice` | any | no | Controls which (if any) tool is called by the model. Can be "auto", "none", "required", or an object specifying a particular function. |
| `modalities` | array of string, nullable | no | Output modalities, "text" and/or "image"; defaults to text-only. Including "image" routes the request to the image generation pipeline and returns generated images on the assistant message. |
| `image_config` | `ChatCompletionImageConfig` | no | Image-generation parameters. Only consulted when `modalities` contains "image". |
| `responseFormat` | `ChatCompletionResponseFormat` | no | OpenAI-compatible response_format (`json_object` or `json_schema`). When set, the parsed content is exposed on `parsed` so later steps can reference fields via `$ref` paths such as `output.parsed.lyrics`. |

### Types used by the request body

#### ChatCompletionMessage

Schema `ChatCompletionMessage`.

Polymorphic: the `role` field selects the concrete type — `user` → `UserMessage`, `system` → `SystemMessage`, `assistant` → `AssistantMessage`, `tool` → `ToolMessage`.

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | string | yes |  |

#### ChatCompletionTool

Schema `ChatCompletionTool`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes |  |
| `function` | `ChatCompletionFunction` | no |  |
| `parameters` | any | no | Server-tool parameters for providers such as OpenRouter. |

#### ChatCompletionImageConfig

Schema `ChatCompletionImageConfig` — Image generation parameters used when `modalities` contains "image". Mirrors OpenRouter's `image_config` shape on chat-completion requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `aspect_ratio` | string, one of `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, nullable | no |  |
| `image_size` | string, one of `0.5K`, `1K`, `2K`, `4K`, nullable | no | Approximate output resolution. "1K" ≈ 1MP, "2K" ≈ 2MP, etc. Engines clamp to their supported range. |
| `n` | integer (int32), nullable | no | Number of images to generate. Engines may clamp to their supported maximum. (minimum `1`, maximum `10`) |

#### ChatCompletionResponseFormat

Schema `ChatCompletionResponseFormat` — OpenAI-compatible response_format. For `json_object` or `json_schema` the content is parsed server-side and exposed on `parsed` for `$ref` paths like `output.parsed.<field>`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes | OpenAI-compatible value: `text`, `json_object`, or `json_schema`. (minLength `1`) |
| `jsonSchema` | `ChatCompletionJsonSchema` | no | Required when `type` is `json_schema`. Ignored otherwise. |

## Responses

### 200 OK

Content type: `application/json`.

Schema `ChatCompletionOutput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `object` | string | no | (default `"chat.completion"`) |
| `created` | integer (int64) | yes | Unix timestamp of when the completion was created. |
| `model` | string | yes |  |
| `choices` | array of `ChatCompletionChoice` | yes |  |
| `usage` | `ChatCompletionUsage` | no |  |
| `systemFingerprint` | string, nullable | no |  |
| `parsed` | any | no | Parsed JSON of `Choices[0].Message.Content`, populated when the request used a JSON `response_format` and the content parsed. Reachable from later steps via `$ref` paths like `output.parsed.<field>`. |

### 400 Bad Request

Content type: `application/json`.

Schema `ProblemDetails`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string, nullable | no |  |
| `title` | string, nullable | no |  |
| `status` | integer (int32), nullable | no |  |
| `detail` | string, nullable | no |  |
| `instance` | string, nullable | no |  |

### 401 Unauthorized

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.

### 403 Forbidden

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.