Responses

Create and manage model responses.

Create a model response

post

Creates a model response.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

top_logprobsinteger · max: 20Optional

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

temperaturenumber · max: 2 · nullableOptional

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

Default: 1Example: 1

top_pnumber · max: 1 · nullableOptional

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

Default: 1Example: 1

userstringOptionalDeprecated

Deprecated in favor of safety_identifier and prompt_cache_key; use prompt_cache_key to maintain caching. A stable end-user identifier to improve cache hit rates and help detect abuse.

Example: user-1234

safety_identifierstringOptional

A stable identifier used to help detect users who may violate usage policies. Use a unique per-user string (e.g., a hash of username or email) to avoid sending identifying information.

Example: safety-identifier-1234

prompt_cache_keystringOptional

Used to cache responses for similar requests and improve cache hit rates. Replaces the user field.

Example: prompt-cache-key-1234

service_tierstring · enum · nullableOptional

Specifies the processing tier for the request. The response includes the actual tier used, which may differ from the requested value.

Default: autoPossible values:

prompt_cache_retentionstring · enum · nullableOptional

Retention policy for the prompt cache. Set to 24h to keep cached prefixes active longer (up to 24 hours).

Possible values:

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Cannot be used with conversation.

modelstringRequired

Model ID used to generate the response (e.g., gpt-4o or o3). See your provider's model guide for available options.

backgroundboolean · nullableOptional

Whether to run the model response in the background.

Default: false

max_output_tokensinteger · nullableOptional

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

max_tool_callsinteger · nullableOptional

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

tool_choiceany ofOptional

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

string · enumOptional

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

Possible values:

or

or

or

or

or

or

or

truncationstring · enum · nullableOptional

The truncation strategy to use for the model response.

• auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
• disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

Default: disabledPossible values:

inputany ofOptional

Text, image, or file inputs used to generate a response. Use this to provide content the model should consider.

stringOptional

A text input to the model, equivalent to a text input with the user role.

or

parallel_tool_callsboolean · nullableOptional

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

Default: true

storeboolean · nullableOptional

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

Default: true

instructionsstring · nullableOptional

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

streamboolean · nullableOptional

If set to true, the model response data will be streamed to the client as it is generated using server-sent events.

Default: false

conversationany of · nullableOptional

The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes.

stringOptional

The unique ID of the conversation.

or

Responses

200

OK

top_logprobsinteger · max: 20 · nullableOptional

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

temperaturenumber · max: 2 · nullableRequired

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

Default: 1Example: 1

top_pnumber · max: 1 · nullableRequired

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

Default: 1Example: 1

userstringOptionalDeprecated

Deprecated in favor of safety_identifier and prompt_cache_key; use prompt_cache_key to maintain caching. A stable end-user identifier to improve cache hit rates and help detect abuse.

Example: user-1234

safety_identifierstringOptional

A stable identifier used to help detect users who may violate usage policies. Use a unique per-user string (e.g., a hash of username or email) to avoid sending identifying information.

Example: safety-identifier-1234

prompt_cache_keystringOptional

Used to cache responses for similar requests and improve cache hit rates. Replaces the user field.

Example: prompt-cache-key-1234

service_tierstring · enum · nullableOptional

Specifies the processing tier for the request. The response includes the actual tier used, which may differ from the requested value.

Default: autoPossible values:

prompt_cache_retentionstring · enum · nullableOptional

Retention policy for the prompt cache. Set to 24h to keep cached prefixes active longer (up to 24 hours).

Possible values:

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Cannot be used with conversation.

modelstringRequired

Model ID used to generate the response (e.g., gpt-4o or o3). See your provider's model guide for available options.

backgroundboolean · nullableOptional

Whether to run the model response in the background.

Default: false

max_output_tokensinteger · nullableOptional

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

max_tool_callsinteger · nullableOptional

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

tool_choiceany ofRequired

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

string · enumOptional

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

Possible values:

or

or

or

or

or

or

or

truncationstring · enum · nullableOptional

The truncation strategy to use for the model response.

• auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
• disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

Default: disabledPossible values:

idstringRequired

Unique identifier for this Response.

objectstring · enumRequired

The object type of this resource - always set to response.

Possible values:

statusstring · enumOptional

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

Possible values:

created_atnumberRequired

Unix timestamp (in seconds) of when this Response was created.

instructionsany of · nullableRequired

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

stringOptional

A text input to the model, equivalent to a text input with the developer role.

or

output_textstring · nullableOptional

SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs.

parallel_tool_callsbooleanRequired

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

Default: true

providerstringOptional

The upstream provider that served the request (e.g. openai). Nexos extension.

completed_atnumber · nullableOptional

Unix timestamp (in seconds) of when the response generation completed. Passed through from the upstream provider.

storebooleanOptional

Whether the response is stored for later retrieval. Echoed from the request by the upstream provider.

frequency_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

presence_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

moderationobject · nullableOptional

Moderation details passed through from the upstream provider, when available.

post/v1/responses

POST /v1/responses HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "model": "GPT 5.6 Sol",
  "input": "how many letters 'r' are in the word 'strawberry'?"
}

200

OK

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "top_logprobs": 1,
  "temperature": 1,
  "top_p": 1,
  "safety_identifier": "safety-identifier-1234",
  "prompt_cache_key": "prompt-cache-key-1234",
  "service_tier": "auto",
  "prompt_cache_retention": "in-memory",
  "previous_response_id": "text",
  "model": "text",
  "reasoning": {
    "effort": "medium",
    "mode": "standard",
    "summary": "auto"
  },
  "background": false,
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tools": [
    {
      "type": "function",
      "name": "text",
      "description": "text",
      "parameters": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "strict": true
    }
  ],
  "tool_choice": "none",
  "prompt": {
    "id": "text",
    "version": "text",
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "truncation": "disabled",
  "id": "text",
  "object": "response",
  "status": "completed",
  "created_at": 1,
  "error": {
    "code": "server_error",
    "message": "text"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "output": [
    {
      "id": "text",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "text",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "text",
              "index": 1,
              "filename": "text"
            }
          ],
          "logprobs": [
            {
              "token": "text",
              "logprob": 1,
              "bytes": [
                1
              ],
              "top_logprobs": [
                {
                  "token": "text",
                  "logprob": 1,
                  "bytes": [
                    1
                  ]
                }
              ]
            }
          ]
        }
      ],
      "status": "in_progress"
    }
  ],
  "instructions": "text",
  "output_text": "text",
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1,
      "cache_write_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 1,
    "nexos_credits_cost": 1
  },
  "parallel_tool_calls": true,
  "conversation": {
    "id": "text"
  },
  "provider": "text",
  "completed_at": 1,
  "store": true,
  "frequency_penalty": 1,
  "presence_penalty": 1,
  "moderation": {},
  "content_filters": [
    {
      "blocked": true,
      "source_type": "text",
      "content_filter_raw": [
        {}
      ],
      "content_filter_results": {},
      "content_filter_offsets": {
        "check_offset": 1,
        "start_offset": 1,
        "end_offset": 1
      }
    }
  ],
  "tool_usage": {
    "image_gen": {
      "input_tokens": 1,
      "input_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "output_tokens": 1,
      "output_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "total_tokens": 1
    },
    "web_search": {
      "num_requests": 1
    }
  }
}

Get a model response

get

Retrieves a model response with the given ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

response_idstringRequired

The ID of the response to retrieve.

Example: resp_677efb5139a88190b512bc3fef8e535d

Query parameters

streambooleanOptional

If set to true, the model response data will be streamed to the client as it is generated using server-sent events.

starting_afterintegerOptional

The sequence number of the event after which to start streaming.

include_obfuscationbooleanOptional

When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an obfuscation field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream.

Responses

200

OK

application/json

top_logprobsinteger · max: 20 · nullableOptional

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

temperaturenumber · max: 2 · nullableRequired

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

Default: 1Example: 1

top_pnumber · max: 1 · nullableRequired

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

Default: 1Example: 1

userstringOptionalDeprecated

Deprecated in favor of safety_identifier and prompt_cache_key; use prompt_cache_key to maintain caching. A stable end-user identifier to improve cache hit rates and help detect abuse.

Example: user-1234

safety_identifierstringOptional

A stable identifier used to help detect users who may violate usage policies. Use a unique per-user string (e.g., a hash of username or email) to avoid sending identifying information.

Example: safety-identifier-1234

prompt_cache_keystringOptional

Used to cache responses for similar requests and improve cache hit rates. Replaces the user field.

Example: prompt-cache-key-1234

service_tierstring · enum · nullableOptional

Specifies the processing tier for the request. The response includes the actual tier used, which may differ from the requested value.

Default: autoPossible values:

prompt_cache_retentionstring · enum · nullableOptional

Retention policy for the prompt cache. Set to 24h to keep cached prefixes active longer (up to 24 hours).

Possible values:

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Cannot be used with conversation.

modelstringRequired

Model ID used to generate the response (e.g., gpt-4o or o3). See your provider's model guide for available options.

backgroundboolean · nullableOptional

Whether to run the model response in the background.

Default: false

max_output_tokensinteger · nullableOptional

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

max_tool_callsinteger · nullableOptional

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

tool_choiceany ofRequired

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

string · enumOptional

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

Possible values:

or

or

or

or

or

or

or

truncationstring · enum · nullableOptional

The truncation strategy to use for the model response.

• auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
• disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

Default: disabledPossible values:

idstringRequired

Unique identifier for this Response.

objectstring · enumRequired

The object type of this resource - always set to response.

Possible values:

statusstring · enumOptional

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

Possible values:

created_atnumberRequired

Unix timestamp (in seconds) of when this Response was created.

instructionsany of · nullableRequired

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

stringOptional

A text input to the model, equivalent to a text input with the developer role.

or

output_textstring · nullableOptional

SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs.

parallel_tool_callsbooleanRequired

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

Default: true

providerstringOptional

The upstream provider that served the request (e.g. openai). Nexos extension.

completed_atnumber · nullableOptional

Unix timestamp (in seconds) of when the response generation completed. Passed through from the upstream provider.

storebooleanOptional

Whether the response is stored for later retrieval. Echoed from the request by the upstream provider.

frequency_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

presence_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

moderationobject · nullableOptional

Moderation details passed through from the upstream provider, when available.

get/v1/responses/{response_id}

GET /v1/responses/{response_id} HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "top_logprobs": 1,
  "temperature": 1,
  "top_p": 1,
  "safety_identifier": "safety-identifier-1234",
  "prompt_cache_key": "prompt-cache-key-1234",
  "service_tier": "auto",
  "prompt_cache_retention": "in-memory",
  "previous_response_id": "text",
  "model": "text",
  "reasoning": {
    "effort": "medium",
    "mode": "standard",
    "summary": "auto"
  },
  "background": false,
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tools": [
    {
      "type": "function",
      "name": "text",
      "description": "text",
      "parameters": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "strict": true
    }
  ],
  "tool_choice": "none",
  "prompt": {
    "id": "text",
    "version": "text",
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "truncation": "disabled",
  "id": "text",
  "object": "response",
  "status": "completed",
  "created_at": 1,
  "error": {
    "code": "server_error",
    "message": "text"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "output": [
    {
      "id": "text",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "text",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "text",
              "index": 1,
              "filename": "text"
            }
          ],
          "logprobs": [
            {
              "token": "text",
              "logprob": 1,
              "bytes": [
                1
              ],
              "top_logprobs": [
                {
                  "token": "text",
                  "logprob": 1,
                  "bytes": [
                    1
                  ]
                }
              ]
            }
          ]
        }
      ],
      "status": "in_progress"
    }
  ],
  "instructions": "text",
  "output_text": "text",
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1,
      "cache_write_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 1,
    "nexos_credits_cost": 1
  },
  "parallel_tool_calls": true,
  "conversation": {
    "id": "text"
  },
  "provider": "text",
  "completed_at": 1,
  "store": true,
  "frequency_penalty": 1,
  "presence_penalty": 1,
  "moderation": {},
  "content_filters": [
    {
      "blocked": true,
      "source_type": "text",
      "content_filter_raw": [
        {}
      ],
      "content_filter_results": {},
      "content_filter_offsets": {
        "check_offset": 1,
        "start_offset": 1,
        "end_offset": 1
      }
    }
  ],
  "tool_usage": {
    "image_gen": {
      "input_tokens": 1,
      "input_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "output_tokens": 1,
      "output_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "total_tokens": 1
    },
    "web_search": {
      "num_requests": 1
    }
  }
}

Delete a model response

delete

Deletes a model response with the given ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

response_idstringRequired

The ID of the response to delete.

Example: resp_677efb5139a88190b512bc3fef8e535d

Responses

200

OK

No content

404

Not Found

application/json

delete/v1/responses/{response_id}

DELETE /v1/responses/{response_id} HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List input items

get

Returns a list of input items for a given response.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

response_idstringRequired

The ID of the response to retrieve input items for.

Query parameters

limitintegerOptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Default: 20

orderstring · enumOptional

The order to return the input items in. Default is desc.

• asc: Return the input items in ascending order.
• desc: Return the input items in descending order.

Possible values:

afterstringOptional

An item ID to list items after, used in pagination.

Responses

200

OK

application/json

A list of Response items.

objectconst: listRequired

The type of object returned, must be list.

has_morebooleanRequired

Whether there are more items available.

first_idstringRequired

The ID of the first item in the list.

last_idstringRequired

The ID of the last item in the list.

get/v1/responses/{response_id}/input_items

GET /v1/responses/{response_id}/input_items HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "object": null,
  "data": [
    {
      "type": "message",
      "role": "user",
      "status": "in_progress",
      "content": [
        {
          "type": "input_text",
          "text": "text"
        }
      ],
      "id": "text"
    }
  ],
  "has_more": true,
  "first_id": "text",
  "last_id": "text"
}

Cancel a response

post

Cancels a model response with the given ID. Only responses created with the background parameter set to true can be cancelled.

Note: background responses are temporarily disabled on the platform — requests with background: true currently return error 100101, so this operation cannot be used until background responses are re-enabled.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

response_idstringRequired

The ID of the response to cancel.

Example: resp_677efb5139a88190b512bc3fef8e535d

Responses

200

OK

application/json

top_logprobsinteger · max: 20 · nullableOptional

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

temperaturenumber · max: 2 · nullableRequired

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

Default: 1Example: 1

top_pnumber · max: 1 · nullableRequired

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

Default: 1Example: 1

userstringOptionalDeprecated

Deprecated in favor of safety_identifier and prompt_cache_key; use prompt_cache_key to maintain caching. A stable end-user identifier to improve cache hit rates and help detect abuse.

Example: user-1234

safety_identifierstringOptional

A stable identifier used to help detect users who may violate usage policies. Use a unique per-user string (e.g., a hash of username or email) to avoid sending identifying information.

Example: safety-identifier-1234

prompt_cache_keystringOptional

Used to cache responses for similar requests and improve cache hit rates. Replaces the user field.

Example: prompt-cache-key-1234

service_tierstring · enum · nullableOptional

Specifies the processing tier for the request. The response includes the actual tier used, which may differ from the requested value.

Default: autoPossible values:

prompt_cache_retentionstring · enum · nullableOptional

Retention policy for the prompt cache. Set to 24h to keep cached prefixes active longer (up to 24 hours).

Possible values:

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Cannot be used with conversation.

modelstringRequired

Model ID used to generate the response (e.g., gpt-4o or o3). See your provider's model guide for available options.

backgroundboolean · nullableOptional

Whether to run the model response in the background.

Default: false

max_output_tokensinteger · nullableOptional

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

max_tool_callsinteger · nullableOptional

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

tool_choiceany ofRequired

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

string · enumOptional

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

Possible values:

or

or

or

or

or

or

or

truncationstring · enum · nullableOptional

The truncation strategy to use for the model response.

• auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
• disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

Default: disabledPossible values:

idstringRequired

Unique identifier for this Response.

objectstring · enumRequired

The object type of this resource - always set to response.

Possible values:

statusstring · enumOptional

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

Possible values:

created_atnumberRequired

Unix timestamp (in seconds) of when this Response was created.

instructionsany of · nullableRequired

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

stringOptional

A text input to the model, equivalent to a text input with the developer role.

or

output_textstring · nullableOptional

SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs.

parallel_tool_callsbooleanRequired

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

Default: true

providerstringOptional

The upstream provider that served the request (e.g. openai). Nexos extension.

completed_atnumber · nullableOptional

Unix timestamp (in seconds) of when the response generation completed. Passed through from the upstream provider.

storebooleanOptional

Whether the response is stored for later retrieval. Echoed from the request by the upstream provider.

frequency_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

presence_penaltynumber · nullableOptional

Echoed by some upstream providers alongside the response.

moderationobject · nullableOptional

Moderation details passed through from the upstream provider, when available.

404

Not Found

application/json

post/v1/responses/{response_id}/cancel

POST /v1/responses/{response_id}/cancel HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "top_logprobs": 1,
  "temperature": 1,
  "top_p": 1,
  "safety_identifier": "safety-identifier-1234",
  "prompt_cache_key": "prompt-cache-key-1234",
  "service_tier": "auto",
  "prompt_cache_retention": "in-memory",
  "previous_response_id": "text",
  "model": "text",
  "reasoning": {
    "effort": "medium",
    "mode": "standard",
    "summary": "auto"
  },
  "background": false,
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tools": [
    {
      "type": "function",
      "name": "text",
      "description": "text",
      "parameters": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "strict": true
    }
  ],
  "tool_choice": "none",
  "prompt": {
    "id": "text",
    "version": "text",
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "truncation": "disabled",
  "id": "text",
  "object": "response",
  "status": "completed",
  "created_at": 1,
  "error": {
    "code": "server_error",
    "message": "text"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "output": [
    {
      "id": "text",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "text",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "text",
              "index": 1,
              "filename": "text"
            }
          ],
          "logprobs": [
            {
              "token": "text",
              "logprob": 1,
              "bytes": [
                1
              ],
              "top_logprobs": [
                {
                  "token": "text",
                  "logprob": 1,
                  "bytes": [
                    1
                  ]
                }
              ]
            }
          ]
        }
      ],
      "status": "in_progress"
    }
  ],
  "instructions": "text",
  "output_text": "text",
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1,
      "cache_write_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 1,
    "nexos_credits_cost": 1
  },
  "parallel_tool_calls": true,
  "conversation": {
    "id": "text"
  },
  "provider": "text",
  "completed_at": 1,
  "store": true,
  "frequency_penalty": 1,
  "presence_penalty": 1,
  "moderation": {},
  "content_filters": [
    {
      "blocked": true,
      "source_type": "text",
      "content_filter_raw": [
        {}
      ],
      "content_filter_results": {},
      "content_filter_offsets": {
        "check_offset": 1,
        "start_offset": 1,
        "end_offset": 1
      }
    }
  ],
  "tool_usage": {
    "image_gen": {
      "input_tokens": 1,
      "input_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "output_tokens": 1,
      "output_tokens_details": {
        "image_tokens": 1,
        "text_tokens": 1
      },
      "total_tokens": 1
    },
    "web_search": {
      "num_requests": 1
    }
  }
}

Compact a response

post

Compact conversation

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

modelstringOptional

Model ID used to generate the response, like gpt-5 or o3.

inputany of · nullableOptional

Text, image, or file inputs to the model, used to generate a response

string · max: 10485760Optional

A text input to the model, equivalent to a text input with the user role.

or

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations.

Example: resp_123

instructionsstring · nullableOptional

A system (or developer) message inserted into the model's context. When used along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

Responses

200

Success

application/json

idstringRequired

The unique identifier for the compacted response.

objectstring · enumRequired

The object type. Always response.compaction.

Default: response.compactionPossible values:

created_atintegerRequired

Unix timestamp (in seconds) when the compacted conversation was created.

post/v1/responses/compact

POST /v1/responses/compact HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "model": "GPT 5.6 Sol",
  "previous_response_id": "resp_689c2f9e0f508190a2030b8479227d05",
  "input": []
}

200

Success

{
  "id": "text",
  "object": "response.compaction",
  "output": [
    {
      "id": "text",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "text",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "text",
              "index": 1,
              "filename": "text"
            }
          ],
          "logprobs": [
            {
              "token": "text",
              "logprob": 1,
              "bytes": [
                1
              ],
              "top_logprobs": [
                {
                  "token": "text",
                  "logprob": 1,
                  "bytes": [
                    1
                  ]
                }
              ]
            }
          ]
        }
      ],
      "status": "in_progress"
    }
  ],
  "created_at": 1,
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1,
      "cache_write_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 1,
    "nexos_credits_cost": 1
  }
}

Get input token counts

post

Get input token counts.

Note: this operation is currently rejected by the upstream providers of all available models (it requires provider-side Responses API support that none of the currently configured providers offer).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

modelstring · nullableOptional

Model ID used to generate the response, like gpt-4o or o3.

inputany of · nullableOptional

Text, image, or file inputs to the model, used to generate a response

string · max: 10485760Optional

A text input to the model, equivalent to a text input with the user role.

or

previous_response_idstring · nullableOptional

The unique ID of the previous response to the model. Use this to create multi-turn conversations.

Example: resp_123

truncationstring · enumOptional

The truncation strategy to use for the model response. - auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

Possible values:

instructionsstring · nullableOptional

A system (or developer) message inserted into the model's context. When used along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

conversationany of · nullableOptional

The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes.

stringOptional

The unique ID of the conversation.

or

tool_choiceany of · nullableOptional

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

string · enumOptional

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

Possible values:

or

or

or

or

or

or

or

parallel_tool_callsboolean · nullableOptional

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

Responses

200

Success

application/json

objectstring · enumRequiredDefault: response.input_tokensPossible values:

input_tokensintegerRequired

post/v1/responses/input_tokens

POST /v1/responses/input_tokens HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "model": "GPT 5.6 Sol",
  "input": "how many letters 'r' are in the word 'strawberry'?"
}

200

Success

{
  "object": "response.input_tokens",
  "input_tokens": 123
}