Responses

Використовуйте CometAPI POST /v1/responses для генерації розширених вихідних даних моделі з multimodal input, stateful chat, built-in tools і function calling.

POST /v1/responses

Python

Text Input

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

response = client.responses.create(
    model="gpt-5.4",
    input="Tell me a three sentence bedtime story about a unicorn.",
)

print(response.output_text)

200

{
  "id": "resp_0a153ae8201f73bc0069a7e8044cc481",
  "object": "response",
  "created_at": 1772611588,
  "status": "completed",
  "background": false,
  "completed_at": 1772611589,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1-nano",
  "output": [
    {
      "id": "msg_0a153ae8201f73bc0069a7e8049a8881",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "Four."
        }
      ],
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "auto",
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 9,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 28
  },
  "user": null,
  "metadata": {}
}

​

Огляд

Responses API — це розширений endpoint CometAPI для генерації відповідей моделі. Він надає багатший інтерфейс, ніж Chat Completions, із вбудованою підтримкою multimodal inputs, stateful conversations, інтеграції інструментів і структурованих вихідних даних — усе через один endpoint.

​

Ключові можливості

• Multimodal Input — Приймає як вхідні дані текст, зображення, файли (включно з PDF) і URL
• Stateful Conversations — Об’єднуйте відповіді в ланцюжок за допомогою previous_response_id або conversation, не керуючи історією повідомлень самостійно
• Built-in Tools — Використовуйте web_search_preview, file_search, code_interpreter та інші без будь-якого налаштування
• Function Calling — Визначайте власні функції, які модель може викликати зі структурованими аргументами
• Structured Outputs — Запитуйте вихідні дані, що відповідають JSON Schema, через параметр text.format
• Reasoning Models — Налаштовуйте глибину міркування за допомогою параметра reasoning.effort для моделей o-series і gpt-5
• Streaming — Передавайте відповіді потоком через SSE із детальними типами подій (response.output_text.delta, response.completed тощо)

​

Важливі примітки

Варіації моделей — Різні провайдери моделей можуть підтримувати різні параметри запиту та повертати різні поля відповіді. Не всі параметри підтримуються кожною моделлю, доступною в CometAPI.

Принцип pass-through — CometAPI пересилає запити провайдерам моделей і повертає їхні відповіді без змін, гарантуючи, що ви отримуєте результат, узгоджений з оригінальним API. Об’єкт відповіді також повертає багато параметрів запиту (як-от temperature, tools, reasoning) для прозорості.

​

Події Streaming

Коли stream встановлено в true, API надсилає server-sent events (SSE) у такому порядку:

1. response.created — Об’єкт відповіді ініціалізовано
2. response.in_progress — Генерацію розпочато
3. response.output_item.added — Додано новий елемент вихідних даних (повідомлення або виклик інструмента)
4. response.content_part.added — Частину контенту розпочато
5. response.output_text.delta — Фрагмент тексту (містить поле delta із текстовим фрагментом)
6. response.output_text.done — Генерацію тексту для цієї частини контенту завершено
7. response.content_part.done — Частину контенту завершено
8. response.output_item.done — Елемент вихідних даних завершено
9. response.completed — Повна відповідь із даними usage

​

Довідкова документація

Для детальних описів параметрів дивіться інтерактивний API playground вище. Документація провайдера:

• Text Inputs and Outputs
• Image Inputs
• File Inputs (PDF)
• Structured Outputs
• Function Calling
• Conversation State
• Built-in Tools
• Reasoning Models

---

Авторизації

Authorization · string · header · обов'язково

Bearer token authentication. Use your CometAPI key.

Тіло

application/json

model · string · обов'язково

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

Приклад:

"gpt-5.4"

input · string object[] · обов'язково

Text, image, or file inputs to the model, used to generate a response. Can be a simple string for text-only input, or an array of input items for multimodal content (images, files) and multi-turn conversations.

instructions · string

A system (or developer) message inserted into the model's context. When used with previous_response_id, instructions from the previous response are not carried over — this makes it easy to swap system messages between turns.

background · boolean · за замовчуванням: false

Whether to run the model response in the background. Background responses do not return output directly — you retrieve the result later via the response ID.

context_management · object[]

Context management configuration for this request. Controls how the model manages context when the conversation exceeds the context window.

Show child attributes

conversation · string object

The conversation this response belongs to. Items from the conversation are prepended to input for context. Input and output items are automatically added to the conversation after the response completes. Cannot be used with previous_response_id.

include · enum<string>[]

Additional output data to include in the response. Use this to request extra information that is not included by default.

Доступні опції: web_search_call.action.sources, code_interpreter_call.outputs, computer_call_output.output.image_url, file_search_call.results, message.input_image.image_url, message.output_text.logprobs, reasoning.encrypted_content

max_output_tokens · integer

An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

max_tool_calls · integer

The maximum number of total calls to built-in tools that can be processed in a response. This limit applies across all built-in tool calls, not per individual tool. Any further tool call attempts by the model will be ignored.

metadata · object

Set of up to 16 key-value pairs that can be attached to the response. Useful for storing additional information in a structured format. Keys have a maximum length of 64 characters; values have a maximum length of 512 characters.

Show child attributes

parallel_tool_calls · boolean · за замовчуванням: true

Whether to allow the model to run tool calls in parallel.

previous_response_id · string

The unique ID of a previous response. Use this to create multi-turn conversations without manually managing conversation state. Cannot be used with conversation.

prompt · object

Reference to a prompt template and its variables.

Show child attributes

prompt_cache_key · string

A key used to cache responses for similar requests, helping optimize cache hit rates. Replaces the deprecated user field for caching purposes.

prompt_cache_retention · enum<string>

The retention policy for the prompt cache. Set to 24h to keep cached prefixes active for up to 24 hours.

Доступні опції: in-memory, 24h

reasoning · object

Configuration options for reasoning models (o-series and gpt-5). Controls the depth of reasoning before generating a response.

Show child attributes

safety_identifier · string

A stable identifier for your end-users, used to help detect policy violations. Should be a hashed username or email — do not send identifying information directly.

Maximum string length: 64

service_tier · enum<string>

Specifies the processing tier for the request. When set, the response will include the actual service_tier used.

• auto: Uses the tier configured in project settings (default behavior).
• default: Standard pricing and performance.
• flex: Flexible processing with potential cost savings.
• priority: Priority processing with faster response times.

Доступні опції: auto, default, flex, priority

store · boolean · за замовчуванням: true

Whether to store the generated response for later retrieval via API.

stream · boolean · за замовчуванням: false

If set to true, the response data will be streamed to the client as it is generated using server-sent events (SSE). Events include response.created, response.output_text.delta, response.completed, and more.

stream_options · object

Options for streaming responses. Only set this when stream is true.

Show child attributes

temperature · number · за замовчуванням: 1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) increase randomness; lower values (e.g., 0.2) make output more focused and deterministic. We recommend adjusting either this or top_p, but not both.

Необхідний діапазон: 0 <= x <= 2

text · object

Configuration for text output. Use this to request structured JSON output via JSON mode or JSON Schema.

Show child attributes

tool_choice · string object · за замовчуванням: auto

Controls how the model selects which tool(s) to call.

• auto (default): The model decides whether and which tools to call.
• none: The model will not call any tools.
• required: The model must call at least one tool.
• An object specifying a particular tool to use.

tools · object[]

An array of tools the model may call while generating a response. CometAPI supports three categories:

• Built-in tools: Platform-provided tools like web_search_preview and file_search.
• Function calls: Custom functions you define, enabling the model to call your own code with structured arguments.
• MCP tools: Integrations with third-party systems via MCP servers.

top_logprobs · integer

Number of most likely tokens to return at each position (0–20), each with an associated log probability. Must include message.output_text.logprobs in the include parameter to receive logprobs.

Необхідний діапазон: 0 <= x <= 20

top_p · number · за замовчуванням: 1

Nucleus sampling parameter. The model considers tokens with top_p cumulative probability mass. For example, 0.1 means only the top 10% probability tokens are considered. We recommend adjusting either this or temperature, but not both.

Необхідний діапазон: 0 <= x <= 1

truncation · enum<string> · за замовчуванням: disabled

The truncation strategy for handling inputs that exceed the model's context window.

• auto: The model truncates the input by dropping items from the beginning of the conversation to fit.
• disabled (default): The request fails with a 400 error if the input exceeds the context window.

Доступні опції: auto, disabled

user · string · застаріло

Deprecated. Use safety_identifier and prompt_cache_key instead. A stable identifier for your end-user.

Відповідь

200 - application/json

The generated Response object.

id · string

Unique identifier for the response.

Приклад:

"resp_0a153ae8201f73bc0069a7e8044cc481"

object · enum<string>

The object type, always response.

Доступні опції: response

Приклад:

"response"

created_at · integer

Unix timestamp (in seconds) of when the response was created.

Приклад:

1772611588

status · enum<string>

The status of the response.

Доступні опції: completed, in_progress, failed, cancelled, queued

Приклад:

"completed"

background · boolean

Whether the response was run in the background.

Приклад:

false

completed_at · integer | null

Unix timestamp of when the response was completed, or null if still in progress.

Приклад:

1772611589

error · object

Error information if the response failed, or null on success.

Show child attributes

incomplete_details · object

Details about why the response is incomplete, if applicable.

Show child attributes

instructions · string | null

The system instructions used for this response.

max_output_tokens · integer | null

The maximum output token limit that was applied.

model · string

The model used for the response.

Приклад:

"gpt-4.1-nano"

output · object[]

An array of output items generated by the model. Each item can be a message, function call, or other output type.

Show child attributes

output_text · string

A convenience field containing the concatenated text output from all output message items.

parallel_tool_calls · boolean

Whether parallel tool calls were enabled.

previous_response_id · string | null

The ID of the previous response, if this is a multi-turn conversation.

reasoning · object

The reasoning configuration that was used.

Show child attributes

service_tier · string

The service tier actually used to process the request.

Приклад:

"default"

store · boolean

Whether the response was stored.

temperature · number

The temperature value used.

Приклад:

1

text · object

The text configuration used.

Show child attributes

tool_choice · string object

The tool choice setting used.

tools · object[]

The tools that were available for this response.

top_p · number

The top_p value used.

Приклад:

1

truncation · string

The truncation strategy used.

usage · object

Token usage statistics for this response.

Show child attributes

user · string | null

The user identifier, if provided.

metadata · object

The metadata attached to this response.

Show child attributes

content_filters · array | null

Content filter results applied to the response, if any.

frequency_penalty · number · за замовчуванням: 0

The frequency penalty applied to the request.

max_tool_calls · integer | null

Maximum number of tool calls allowed, if set.

presence_penalty · number · за замовчуванням: 0

The presence penalty applied to the request.

prompt_cache_key · string | null

Cache key for prompt caching, if applicable.

prompt_cache_retention · string | null

Prompt cache retention policy, if applicable.

safety_identifier · string | null

Safety system identifier for the response, if applicable.

top_logprobs · integer · за замовчуванням: 0

Number of top log probabilities returned per token position.