Chat Types

TypeScript types for OpenAI-compatible chat completions, including messages, tools, and streaming.

OpenAI Compatibility: The Skytells Chat API implements the OpenAI Chat Completions specification. These TypeScript types mirror the OpenAI API exactly for maximum compatibility. See POST /v1/chat/completions for Skytells-specific details.

See Chat for usage.

ChatCompletionMessageParam

type ChatCompletionMessageParam =
  | ChatCompletionSystemMessageParam
  | ChatCompletionUserMessageParam
  | ChatCompletionAssistantMessageParam
  | ChatCompletionToolMessageParam
  | ChatCompletionFunctionMessageParam // deprecated

Union of all message role types.

ChatCompletionSystemMessageParam

interface ChatCompletionSystemMessageParam {
  role: 'system';
  content: string;
  name?: string;
}

Field	Type	Description
`role`	`'system'`	Always `'system'`.
`content`	`string`	System instruction.
`name`	`string`	Optional participant name.

ChatCompletionUserMessageParam

interface ChatCompletionUserMessageParam {
  role: 'user';
  content: string | ContentPart[];
  name?: string;
}

Field	Type	Description
`role`	`'user'`	Always `'user'`.
`content`	`string \| ContentPart[]`	Text or multi-part (text + image). See Vision.
`name`	`string`	Optional participant name.

ChatCompletionAssistantMessageParam

interface ChatCompletionAssistantMessageParam {
  role: 'assistant';
  content: string | null;
  name?: string;
  refusal?: string | null;
  tool_calls?: ChatCompletionMessageToolCall[];
}

Field	Type	Description
`role`	`'assistant'`	Always `'assistant'`.
`content`	`string \| null`	Reply content.
`name`	`string`	Optional name.
`refusal`	`string \| null`	Refusal message.
`tool_calls`	`ChatCompletionMessageToolCall[]`	Tool calls. See Tool Calling.

ChatCompletionToolMessageParam

interface ChatCompletionToolMessageParam {
  role: 'tool';
  content: string;
  tool_call_id: string;
}

Field	Type	Description
`role`	`'tool'`	Always `'tool'`.
`content`	`string`	Tool result (JSON string).
`tool_call_id`	`string`	ID from the tool call.

ChatCompletionTool

interface ChatCompletionTool {
  type: 'function';
  function: {
    name: string;
    description?: string;
    parameters?: Record<string, any>; // JSON Schema
    strict?: boolean;
  };
}

Field	Type	Description
`type`	`'function'`	Always `'function'`.
`function.name`	`string`	Function name.
`function.description`	`string`	Function description.
`function.parameters`	`Record<string, any>`	JSON Schema for parameters.
`function.strict`	`boolean`	Strict schema enforcement.

ChatCompletionToolChoiceOption

type ChatCompletionToolChoiceOption =
  | 'none' 
  | 'auto' 
  | 'required'
  | { type: 'function'; function: { name: string } }

ChatCompletionMessageToolCall

interface ChatCompletionMessageToolCall {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string; // JSON-encoded
  };
}

Field	Type	Description
`id`	`string`	Tool call ID.
`type`	`'function'`	Always `'function'`.
`function.name`	`string`	Function name.
`function.arguments`	`string`	JSON-encoded arguments.

ChatCompletionCreateParams

type ChatCompletionCreateParams =
  | ChatCompletionCreateParamsNonStreaming  // stream?: false
  | ChatCompletionCreateParamsStreaming     // stream: true

interface ChatCompletionCreateParamsBase {
  model: string;
  messages: ChatCompletionMessageParam[];
  max_tokens?: number;
  temperature?: number;
  top_p?: number;
  n?: number;
  stop?: string | string[] | null;
  presence_penalty?: number;
  frequency_penalty?: number;
  logprobs?: boolean | null;
  top_logprobs?: number | null;
  user?: string;
  tools?: ChatCompletionTool[];
  tool_choice?: ChatCompletionToolChoiceOption;
  parallel_tool_calls?: boolean;
}

Parameter	Type	Description
`model`	`string`	Model slug. Browse models in the catalog.
`messages`	`ChatCompletionMessageParam[]`	Conversation history.
`max_tokens`	`number`	Max completion tokens.
`temperature`	`number`	Sampling temperature (0–2).
`top_p`	`number`	Nucleus sampling.
`n`	`number`	Number of choices.
`stop`	`string \| string[]`	Stop sequences.
`presence_penalty`	`number`	Presence penalty (−2 to 2).
`frequency_penalty`	`number`	Frequency penalty (−2 to 2).
`logprobs`	`boolean`	Include log probabilities.
`top_logprobs`	`number`	Top N logprobs per token.
`user`	`string`	End-user identifier.
`tools`	`ChatCompletionTool[]`	Tool definitions.
`tool_choice`	`ChatCompletionToolChoiceOption`	Tool invocation mode.
`parallel_tool_calls`	`boolean`	Allow parallel tool calls.

ChatCompletion

Returned by client.chat.completions.create() from POST /v1/chat/completions. This TypeScript interface matches the OpenAI Chat Completions API response exactly — the SDK performs no transformations.

interface ChatCompletion {
  id: string;
  object: 'chat.completion';
  created: number;
  model: string;
  choices: ChatCompletionChoice[];
  usage: CompletionUsage;
  system_fingerprint: string;
  prompt_filter_results: PromptFilterResult[];
}

Field	Type	Description
`id`	`string`	Completion ID.
`object`	`'chat.completion'`	Object type.
`created`	`number`	Unix timestamp.
`model`	`string`	Model used.
`choices`	`ChatCompletionChoice[]`	Completion choices.
`usage`	`CompletionUsage`	Token usage.
`system_fingerprint`	`string`	System fingerprint.
`prompt_filter_results`	`PromptFilterResult[]`	Safety filter results for prompts. See Safety.

ChatCompletionChoice

interface ChatCompletionChoice {
  index: number;
  message: ChatCompletionMessage;
  finish_reason: string;
  logprobs: unknown;
  content_filter_results: ChoiceContentFilterResults;
}

Field	Type	Description
`index`	`number`	Choice index.
`message`	`ChatCompletionMessage`	`role`, `content`, `tool_calls`, `refusal`.
`finish_reason`	`string`	`'stop'` · `'length'` · `'content_filter'` · `'tool_calls'` · `null`.
`logprobs`	`unknown`	Log probability data.
`content_filter_results`	`ChoiceContentFilterResults`	Per-category filter results.

ChatCompletionChunk

interface ChatCompletionChunk {
  id: string;
  object: 'chat.completion.chunk';
  created: number;
  model: string;
  choices: ChatCompletionChunkChoice[];
  usage: CompletionUsage | null;
  prompt_filter_results: PromptFilterResult[];
}

Streamed via AsyncIterable<ChatCompletionChunk>. See Streaming.

Field	Type	Description
`id`	`string`	Chunk ID (same for all chunks in one completion).
`object`	`'chat.completion.chunk'`	Object type.
`created`	`number`	Unix timestamp.
`model`	`string`	Model used.
`choices`	`ChatCompletionChunkChoice[]`	Chunk choices with `delta`.
`usage`	`CompletionUsage \| null`	Token usage (only on final chunk).
`prompt_filter_results`	`PromptFilterResult[]`	Safety filter results.

CompletionUsage

interface CompletionUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
  completion_tokens_details: CompletionTokensDetails;
  prompt_tokens_details: PromptTokensDetails;
}

Field	Type	Description
`prompt_tokens`	`number`	Input tokens.
`completion_tokens`	`number`	Output tokens.
`total_tokens`	`number`	Total tokens.
`completion_tokens_details`	`CompletionTokensDetails`	`accepted_prediction_tokens`, `audio_tokens`, `reasoning_tokens`, `rejected_prediction_tokens`.
`prompt_tokens_details`	`PromptTokensDetails`	`audio_tokens`, `cached_tokens`.

SDK Chat — Complete chat completions implementation guide
Chat Completions API — API documentation for chat
SDK Safety — Content filtering with wasFiltered()

How is this guide?

On this page