# OpenAI Chat Completion

> OpenAI Chat Completion response with choices, messages, tool calls, and usage.

- Name: `openai-chat-completion`
- Categories: openai
- Depends on: `@open-types/openai-shared`
- Detail page: https://open-types.dev/types/openai-chat-completion

## Install

```bash
# Types only
npx shadcn add @open-types/openai-chat-completion

# Types + Zod v4 validators
npx shadcn add @open-types/openai-chat-completion-zod

# Types + real-world examples
npx shadcn add @open-types/openai-chat-completion-examples
```

## Types

```typescript
import type { OpenAIUsage } from "./openai-shared";

export type OpenAIChatMessageRole = "system" | "user" | "assistant" | "tool";

export interface OpenAIToolCallFunction {
  name: string;
  arguments: string;
}

export interface OpenAIToolCall {
  id: string;
  type: "function";
  function: OpenAIToolCallFunction;
}

export interface OpenAIChatMessage {
  role: OpenAIChatMessageRole;
  content: string | null;
  name?: string;
  tool_calls?: OpenAIToolCall[];
}

export type OpenAIFinishReason =
  | "stop"
  | "length"
  | "tool_calls"
  | "content_filter";

export interface OpenAIChatCompletionChoice {
  index: number;
  message: OpenAIChatMessage;
  finish_reason: OpenAIFinishReason | null;
}

export interface OpenAIChatCompletion {
  id: string;
  object: "chat.completion";
  created: number;
  model: string;
  choices: OpenAIChatCompletionChoice[];
  usage: OpenAIUsage;
  system_fingerprint: string | null;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  OpenAIChatMessageRole,
  OpenAIToolCallFunction,
  OpenAIToolCall,
  OpenAIChatMessage,
  OpenAIFinishReason,
  OpenAIChatCompletionChoice,
  OpenAIChatCompletion,
} from "../types/openai-chat-completion";
import { openAIUsageSchema } from "./openai-shared";

export const openAIChatMessageRoleSchema = z.enum([
  "system",
  "user",
  "assistant",
  "tool",
]) satisfies z.ZodType<OpenAIChatMessageRole>;

export const openAIToolCallFunctionSchema = z.object({
  name: z.string(),
  arguments: z.string(),
}) satisfies z.ZodType<OpenAIToolCallFunction>;

export const openAIToolCallSchema = z.object({
  id: z.string(),
  type: z.literal("function"),
  function: openAIToolCallFunctionSchema,
}) satisfies z.ZodType<OpenAIToolCall>;

export const openAIChatMessageSchema = z.object({
  role: openAIChatMessageRoleSchema,
  content: z.string().nullable(),
  name: z.string().optional(),
  tool_calls: z.array(openAIToolCallSchema).optional(),
}) satisfies z.ZodType<OpenAIChatMessage>;

export const openAIFinishReasonSchema = z.enum([
  "stop",
  "length",
  "tool_calls",
  "content_filter",
]) satisfies z.ZodType<OpenAIFinishReason>;

export const openAIChatCompletionChoiceSchema = z.object({
  index: z.number(),
  message: openAIChatMessageSchema,
  finish_reason: openAIFinishReasonSchema.nullable(),
}) satisfies z.ZodType<OpenAIChatCompletionChoice>;

export const openAIChatCompletionSchema = z.object({
  id: z.string(),
  object: z.literal("chat.completion"),
  created: z.number(),
  model: z.string(),
  choices: z.array(openAIChatCompletionChoiceSchema),
  usage: openAIUsageSchema,
  system_fingerprint: z.string().nullable(),
}) satisfies z.ZodType<OpenAIChatCompletion>;

export type {
  OpenAIChatMessageRole,
  OpenAIToolCallFunction,
  OpenAIToolCall,
  OpenAIChatMessage,
  OpenAIFinishReason,
  OpenAIChatCompletionChoice,
  OpenAIChatCompletion,
} from "../types/openai-chat-completion";
```

## Examples

```typescript
// Source: https://platform.openai.com/docs/api-reference/chat/object
// Captured: 2026-05
import type {
  OpenAIChatMessageRole,
  OpenAIToolCallFunction,
  OpenAIToolCall,
  OpenAIChatMessage,
  OpenAIFinishReason,
  OpenAIChatCompletionChoice,
  OpenAIChatCompletion,
} from "../types/openai-chat-completion";

export const openAIChatMessageRoleExamples = {
  system: "system",
  user: "user",
  assistant: "assistant",
  tool: "tool",
} as const satisfies Record<string, OpenAIChatMessageRole>;

export const openAIFinishReasonExamples = {
  stop: "stop",
  length: "length",
  toolCalls: "tool_calls",
  contentFilter: "content_filter",
} as const satisfies Record<string, OpenAIFinishReason>;

const toolCallFunctionGetWeather = {
  name: "get_current_weather",
  arguments: '{"location":"San Francisco, CA","unit":"celsius"}',
} as const satisfies OpenAIToolCallFunction;

export const openAIToolCallFunctionExamples = {
  weather: toolCallFunctionGetWeather,
  emptyArgs: { name: "ping", arguments: "{}" } satisfies OpenAIToolCallFunction,
  complexArgs: {
    name: "create_event",
    arguments: '{"title":"Standup","start":"2026-05-16T10:00:00Z","attendees":["a@b.c","x@y.z"]}',
  } satisfies OpenAIToolCallFunction,
} as const;

const toolCallWeather = {
  id: "call_abc123",
  type: "function",
  function: toolCallFunctionGetWeather,
} as const satisfies OpenAIToolCall;

export const openAIToolCallExamples = {
  weather: toolCallWeather,
  ping: {
    id: "call_xyz789",
    type: "function",
    function: { name: "ping", arguments: "{}" },
  } satisfies OpenAIToolCall,
} as const;

const assistantMessage = {
  role: "assistant",
  content: "Hello! How can I help you today?",
} as const satisfies OpenAIChatMessage;

const toolCallingAssistantMessage = {
  role: "assistant",
  content: null,
  tool_calls: [toolCallWeather],
} as const satisfies OpenAIChatMessage;

export const openAIChatMessageExamples = {
  assistantText: assistantMessage,
  system: { role: "system", content: "You are a helpful assistant." } satisfies OpenAIChatMessage,
  user: { role: "user", content: "What is the weather in SF?" } satisfies OpenAIChatMessage,
  toolResult: {
    role: "tool",
    content: '{"temperature":18,"unit":"celsius"}',
    name: "get_current_weather",
  } satisfies OpenAIChatMessage,
  assistantToolCall: toolCallingAssistantMessage,
  assistantEmpty: { role: "assistant", content: null } satisfies OpenAIChatMessage,
} as const;

const choiceStop = {
  index: 0,
  message: assistantMessage,
  finish_reason: "stop",
} as const satisfies OpenAIChatCompletionChoice;

export const openAIChatCompletionChoiceExamples = {
  stop: choiceStop,
  length: { ...choiceStop, finish_reason: "length" } satisfies OpenAIChatCompletionChoice,
  contentFilter: { ...choiceStop, finish_reason: "content_filter" } satisfies OpenAIChatCompletionChoice,
  toolCalls: {
    index: 0,
    message: toolCallingAssistantMessage,
    finish_reason: "tool_calls",
  } satisfies OpenAIChatCompletionChoice,
  inProgress: { ...choiceStop, finish_reason: null } satisfies OpenAIChatCompletionChoice,
} as const;

const baseCompletion = {
  id: "chatcmpl-9ABCDe1F2gh3iJK4lmnOPq5rStU6V",
  object: "chat.completion",
  created: 1715865000,
  model: "gpt-4o-mini-2024-07-18",
  choices: [choiceStop],
  usage: { prompt_tokens: 9, completion_tokens: 12, total_tokens: 21 },
  system_fingerprint: "fp_44709d6fcb",
} as const satisfies OpenAIChatCompletion;

export const openAIChatCompletionExamples = {
  helloWorld: baseCompletion,
  toolCalling: {
    ...baseCompletion,
    id: "chatcmpl-9ABCDeToolCalling00000000000",
    choices: [openAIChatCompletionChoiceExamples.toolCalls],
    usage: { prompt_tokens: 82, completion_tokens: 24, total_tokens: 106 },
  } satisfies OpenAIChatCompletion,
  lengthCutoff: {
    ...baseCompletion,
    id: "chatcmpl-9ABCDeLengthCutoff0000000000",
    choices: [openAIChatCompletionChoiceExamples.length],
    usage: { prompt_tokens: 12, completion_tokens: 4096, total_tokens: 4108 },
  } satisfies OpenAIChatCompletion,
  contentFiltered: {
    ...baseCompletion,
    id: "chatcmpl-9ABCDeFiltered000000000000000",
    choices: [openAIChatCompletionChoiceExamples.contentFilter],
  } satisfies OpenAIChatCompletion,
  noFingerprint: {
    ...baseCompletion,
    id: "chatcmpl-9ABCDeNoFingerprint0000000000",
    system_fingerprint: null,
  } satisfies OpenAIChatCompletion,
  multiChoice: {
    ...baseCompletion,
    id: "chatcmpl-9ABCDeMultiChoice0000000000000",
    choices: [
      choiceStop,
      { ...choiceStop, index: 1, message: { role: "assistant", content: "Hi there!" } },
    ],
  } satisfies OpenAIChatCompletion,
} as const;
```