Create a chat completion

POST

chat

completions

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Send conversations through the OpenAI-compatible Chat Completions API. Configure your SDK with base_url="https://api.cometapi.com/v1" and your CometAPI API key. The basic, image, streaming, and structured-output examples use gpt-6-astra. The function-calling example uses gpt-6.1-sol, and the log-probability example uses gpt-4.1.

Use the OpenAI Chat Completions reference for parameter definitions. For GPT-6 Astra tool calling, use Responses, following the OpenAI model guidance.

Message roles

Role	Description
`system`	Sets the assistant’s behavior and personality. Placed at the start of the conversation.
`developer`	Provides application instructions. The GPT-6 Astra examples use this role.
`user`	Messages from the end user.
`assistant`	Previous model responses, used to maintain conversation history.
`tool`	Results from tool/function calls. Must include `tool_call_id` matching the original tool call.

Place application instructions in a developer message before user messages when using the GPT-6 Astra examples.

Send multimodal input

Use an array of content parts to send an image with text:

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe the road and surrounding landscape in this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1200",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "reasoning_effort": "low",
  "max_completion_tokens": 4096
}

Use image_url.detail to select image processing detail. This example uses high.

Stream responses

To receive incremental output, set stream to true. The response is delivered as Server-Sent Events (SSE). Text arrives in chat.completion.chunk objects; this abbreviated example includes the final usage chunk:

data: {"choices":[{"delta":{"content":"","refusal":null,"role":"assistant"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[{"delta":{"content":"Hi"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

: Additional text deltas omitted

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk","usage":{"completion_tokens":12,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens":18,"prompt_tokens_details":{"audio_tokens":0,"cache_write_tokens":0,"cached_tokens":0},"total_tokens":30}}

data: [DONE]

To include token usage statistics in streaming responses, set stream_options.include_usage to true. The usage data appears in a final chunk before [DONE]. Chunks can have an empty choices array; check it before accessing choices[0].

Request structured output

Use response_format to request structured output:

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France? Return the answer and your confidence as a number from 0 to 1."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "The answer to the question."
          },
          "confidence": {
            "type": "number",
            "description": "Confidence between zero and one."
          }
        },
        "required": [
          "answer",
          "confidence"
        ],
        "additionalProperties": false
      }
    }
  }
}

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with the key answer and the capital of France as its value."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_object"
  }
}

JSON Schema mode specifies the required structure. JSON Object mode requests valid JSON without enforcing your schema. Check for a refusal or a length-limited response before consuming the result.

Call tools and functions

Use gpt-6.1-sol with a function definition:

{
  "model": "gpt-6.1-sol",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Boston, MA, in celsius? Use the weather tool."
    }
  ],
  "reasoning_effort": "none",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and state, for example Boston, MA."
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ],
              "description": "Temperature unit."
            }
          },
          "required": [
            "location",
            "unit"
          ],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}

A function call returns finish_reason: "tool_calls" and a message.tool_calls array. Parse the function’s JSON-encoded arguments, execute your function, then append the assistant message and a tool result message with its matching tool_call_id.

Choose request parameters

Model-specific parameters

Use reasoning_effort and max_completion_tokens with GPT-6 Astra. The Functions and Logprobs examples show the request options for gpt-6.1-sol and gpt-4.1, respectively.For Claude- or Gemini-specific request formats, see Anthropic Messages and Gemini Generate content.

max_tokens and max_completion_tokens

Use max_completion_tokens to limit generated tokens for the GPT-6 Astra examples. This includes reasoning and visible output, so allow room for both. max_tokens is a legacy parameter.

Instruction roles

Use developer for application instructions in the GPT-6 Astra examples. Keep end-user content in user messages and preserve previous assistant replies when continuing a conversation.

FAQ

How to handle rate limits?

When encountering 429 Too Many Requests, implement exponential backoff:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-6-astra",
                messages=messages,
                reasoning_effort="low",
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

How to maintain conversation context?

Include the full conversation history in the messages array:

messages = [
    {"role": "developer", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a high-level programming language..."},
    {"role": "user", "content": "What are its main advantages?"},
]

What does `finish_reason` mean?

Value	Meaning
`stop`	Natural completion or hit a stop sequence.
`length`	Reached `max_tokens` or `max_completion_tokens` limit.
`tool_calls`	The model invoked one or more tool/function calls.
`content_filter`	Output was filtered due to content policy.

How to control costs?

Use max_completion_tokens to cap output length.
Compare model pricing and choose a model that meets your workload requirements.
Keep prompts concise — avoid redundant context.
Monitor token usage in the usage response field.

Authorizations

Authorization

string

header

required

Bearer token authentication. Use your CometAPI key.

Body

application/json

model

string

default:gpt-6-astra

required

Model ID to use for this request. See the Models page for current options.

Example:

"gpt-6-astra"

messages

object[]

required

Conversation messages, including instructions, user input, assistant replies, and tool results.

Show child attributes

stream

boolean

If true, partial response tokens are delivered incrementally via server-sent events (SSE). The stream ends with a data: [DONE] message.

temperature

number

Sampling temperature. Omit this field for GPT-6 Astra.

Required range: 0 <= x <= 2

top_p

number

Nucleus sampling threshold. Omit this field for GPT-6 Astra. For sampling overrides, adjust either top_p or temperature.

Required range: 0 <= x <= 1

integer

Number of completion choices to generate for each input message. Defaults to 1.

stop

Stop string or list of up to four strings, for models that support stop sequences.

max_tokens

integer

deprecated

Legacy output-token limit. Use max_completion_tokens for the GPT-6 Astra examples.

presence_penalty

number

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared, encouraging the model to explore new topics.

Required range: -2 <= x <= 2

frequency_penalty

number

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

Required range: -2 <= x <= 2

logit_bias

object

A JSON object mapping token IDs to bias values from -100 to 100. The bias is added to the model's logits before sampling. Values between -1 and 1 subtly adjust likelihood; -100 or 100 effectively ban or force selection of a token.

user

string

A unique identifier for your end-user. Helps with abuse detection and monitoring.

max_completion_tokens

integer

Maximum generated tokens, including visible output and reasoning. Leave enough room for both, as in the image-input example.

response_format

object

Specifies the output format. Use {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {...}} for strict structured output.

Show child attributes

tools

object[]

Function definitions for a model that supports tool calling on Chat Completions. The function example uses GPT-5.6 Sol; use Responses for GPT-6 Astra tool calls.

Show child attributes

tool_choice

Controls how the model selects tools. auto (default): model decides. none: no tools. required: must call a tool.

logprobs

boolean

Return token log probabilities. Use gpt-4.1 as shown in the Logprobs example.

top_logprobs

integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

Required range: 0 <= x <= 20

reasoning_effort

string

Reasoning effort supported by the selected model. The GPT-6 Astra examples use low; the GPT-5.6 Sol function example uses none. See the model reference for other supported levels.

stream_options

object

Options for streaming. Only valid when stream is true.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

Available options:

auto,

default,

flex,

priority

Response

Successful chat completion response.

string

Unique completion identifier.

Example:

"chatcmpl_example"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

Available options:

chat.completion

Example:

"chat.completion"

created

integer

Unix timestamp of creation.

Example:

1788763703

model

string

The model used (may include version suffix).

Example:

"gpt-6-astra"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when returned.

system_fingerprint

string | null

Model configuration fingerprint, when returned.

Last modified on October 8, 2026

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Content moderation

API keys

Message roles

Send multimodal input

Stream responses

Request structured output

Call tools and functions

Choose request parameters

FAQ

How to handle rate limits?

How to maintain conversation context?

What does `finish_reason` mean?

How to control costs?

Authorizations

Body

Response

​Message roles

​Send multimodal input

​Stream responses

​Request structured output

​Call tools and functions

​Choose request parameters

​FAQ

​How to handle rate limits?

​How to maintain conversation context?

​What does finish_reason mean?

​How to control costs?

Authorizations

Body

Response

Message roles

Send multimodal input

Stream responses

Request structured output

Call tools and functions

Choose request parameters

FAQ

How to handle rate limits?

How to maintain conversation context?

What does `finish_reason` mean?

How to control costs?