# OpenAI Chat Completion Chunk

> OpenAI Chat Completion streaming chunk with delta content and tool call fragments.

- Name: `openai-chat-completion-chunk`
- Categories: openai
- Detail page: https://open-types.dev/types/openai-chat-completion-chunk

## Install

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

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

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

## Types

```typescript
export interface OpenAIToolCallChunkFunction {
  name?: string;
  arguments?: string;
}

export interface OpenAIToolCallChunk {
  index: number;
  id?: string;
  type?: "function";
  function?: OpenAIToolCallChunkFunction;
}

export interface OpenAIChatCompletionChunkDelta {
  role?: "system" | "user" | "assistant" | "tool";
  content?: string | null;
  tool_calls?: OpenAIToolCallChunk[];
}

export interface OpenAIChatCompletionChunkChoice {
  index: number;
  delta: OpenAIChatCompletionChunkDelta;
  finish_reason: string | null;
}

export interface OpenAIChatCompletionChunk {
  id: string;
  object: "chat.completion.chunk";
  created: number;
  model: string;
  choices: OpenAIChatCompletionChunkChoice[];
  system_fingerprint: string | null;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  OpenAIToolCallChunkFunction,
  OpenAIToolCallChunk,
  OpenAIChatCompletionChunkDelta,
  OpenAIChatCompletionChunkChoice,
  OpenAIChatCompletionChunk,
} from "../types/openai-chat-completion-chunk";

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

export const openAIToolCallChunkSchema = z.object({
  index: z.number(),
  id: z.string().optional(),
  type: z.literal("function").optional(),
  function: openAIToolCallChunkFunctionSchema.optional(),
}) satisfies z.ZodType<OpenAIToolCallChunk>;

export const openAIChatCompletionChunkDeltaSchema = z.object({
  role: z.enum(["system", "user", "assistant", "tool"]).optional(),
  content: z.string().nullable().optional(),
  tool_calls: z.array(openAIToolCallChunkSchema).optional(),
}) satisfies z.ZodType<OpenAIChatCompletionChunkDelta>;

export const openAIChatCompletionChunkChoiceSchema = z.object({
  index: z.number(),
  delta: openAIChatCompletionChunkDeltaSchema,
  finish_reason: z.string().nullable(),
}) satisfies z.ZodType<OpenAIChatCompletionChunkChoice>;

export const openAIChatCompletionChunkSchema = z.object({
  id: z.string(),
  object: z.literal("chat.completion.chunk"),
  created: z.number(),
  model: z.string(),
  choices: z.array(openAIChatCompletionChunkChoiceSchema),
  system_fingerprint: z.string().nullable(),
}) satisfies z.ZodType<OpenAIChatCompletionChunk>;

export type {
  OpenAIToolCallChunkFunction,
  OpenAIToolCallChunk,
  OpenAIChatCompletionChunkDelta,
  OpenAIChatCompletionChunkChoice,
  OpenAIChatCompletionChunk,
} from "../types/openai-chat-completion-chunk";
```

## Examples

```typescript
// Source: https://platform.openai.com/docs/api-reference/chat-streaming/streaming
// Captured: 2026-05
import type {
  OpenAIToolCallChunkFunction,
  OpenAIToolCallChunk,
  OpenAIChatCompletionChunkDelta,
  OpenAIChatCompletionChunkChoice,
  OpenAIChatCompletionChunk,
} from "../types/openai-chat-completion-chunk";

export const openAIToolCallChunkFunctionExamples = {
  empty: {} satisfies OpenAIToolCallChunkFunction,
  nameOnly: { name: "get_current_weather" } satisfies OpenAIToolCallChunkFunction,
  argsFragment: { arguments: '{"location":' } satisfies OpenAIToolCallChunkFunction,
  full: {
    name: "get_current_weather",
    arguments: '{"location":"SF"}',
  } satisfies OpenAIToolCallChunkFunction,
} as const;

const toolCallStart = {
  index: 0,
  id: "call_abc123",
  type: "function",
  function: { name: "get_current_weather", arguments: "" },
} as const satisfies OpenAIToolCallChunk;

const toolCallContinuation = {
  index: 0,
  function: { arguments: '{"location":"San Francisco' },
} as const satisfies OpenAIToolCallChunk;

export const openAIToolCallChunkExamples = {
  start: toolCallStart,
  continuation: toolCallContinuation,
  indexOnly: { index: 1 } satisfies OpenAIToolCallChunk,
} as const;

export const openAIChatCompletionChunkDeltaExamples = {
  initialRole: { role: "assistant", content: "" } satisfies OpenAIChatCompletionChunkDelta,
  contentChunk: { content: "Hello" } satisfies OpenAIChatCompletionChunkDelta,
  emptyDelta: {} satisfies OpenAIChatCompletionChunkDelta,
  toolCallStart: {
    role: "assistant",
    content: null,
    tool_calls: [toolCallStart],
  } satisfies OpenAIChatCompletionChunkDelta,
  toolCallStream: { tool_calls: [toolCallContinuation] } satisfies OpenAIChatCompletionChunkDelta,
} as const;

const choiceStart = {
  index: 0,
  delta: { role: "assistant", content: "" },
  finish_reason: null,
} as const satisfies OpenAIChatCompletionChunkChoice;

const choiceFinish = {
  index: 0,
  delta: {},
  finish_reason: "stop",
} as const satisfies OpenAIChatCompletionChunkChoice;

export const openAIChatCompletionChunkChoiceExamples = {
  start: choiceStart,
  contentChunk: {
    index: 0,
    delta: { content: "Hello" },
    finish_reason: null,
  } satisfies OpenAIChatCompletionChunkChoice,
  finish: choiceFinish,
  toolCallsFinish: { ...choiceFinish, finish_reason: "tool_calls" } satisfies OpenAIChatCompletionChunkChoice,
} as const;

const baseChunk = {
  id: "chatcmpl-9ABCDe1F2gh3iJK4lmnOPq5rStU6V",
  object: "chat.completion.chunk",
  created: 1715865000,
  model: "gpt-4o-mini-2024-07-18",
  choices: [choiceStart],
  system_fingerprint: "fp_44709d6fcb",
} as const satisfies OpenAIChatCompletionChunk;

export const openAIChatCompletionChunkExamples = {
  start: baseChunk,
  contentChunk: {
    ...baseChunk,
    choices: [openAIChatCompletionChunkChoiceExamples.contentChunk],
  } satisfies OpenAIChatCompletionChunk,
  finish: { ...baseChunk, choices: [choiceFinish] } satisfies OpenAIChatCompletionChunk,
  toolCallsFinish: {
    ...baseChunk,
    choices: [openAIChatCompletionChunkChoiceExamples.toolCallsFinish],
  } satisfies OpenAIChatCompletionChunk,
  noFingerprint: {
    ...baseChunk,
    system_fingerprint: null,
  } satisfies OpenAIChatCompletionChunk,
} as const;
```