Responses

POST /v1/responses

Send input to a model and get one complete response. The Responses endpoint organizes both input and output as structured "items", which keeps function-calling and multimodal flows cleaner.

This endpoint is compatible with the OpenAI Responses SDK. If you already have a project on the OpenAI SDK, just point base_url at CrossModel and set model to a CrossModel model ID — nothing else needs to change.

Endpoint

POST https://api.crossmodel.ai/v1/responses
Authorization: Bearer cm-YOUR_KEY
Content-Type: application/json

Every request must carry a Bearer API key in the Authorization header.

Create response

1curl https://api.crossmodel.ai/v1/responses \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer $CROSSMODEL_API_KEY" \4  -d '{5    "model": "openai/gpt-5-mini",6    "instructions": "You are a helpful assistant.",7    "input": "Hello!"8  }'

Request parameters

Parameter	Type	Required	Notes
`model`	string	Yes	The model ID to use, e.g. `openai/gpt-5-mini`. Call `/v1/models` for the full list.
`input`	string or array	No	The model input. Either a string, or an array of input items (see Input items).
`instructions`	string	No	System-level instructions that set the model's overall behavior; prepended to the input at the highest priority.
`max_output_tokens`	integer	No	Max tokens to generate for this response.
`temperature`	number	No	Sampling temperature, typically `0`–`2`. Higher is more random and varied.
`top_p`	number	No	Nucleus-sampling threshold. Usually adjust either `temperature` or `top_p`, not both.
`tools`	array	No	The tools the model may call. See Function tools below.
`tool_choice`	string or object	No	Controls whether and how the model calls tools: `auto`, `none`, `required`, or an object naming a specific function.
`reasoning`	object	No	Reasoning config. `effort` controls how much reasoning the model spends before answering: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. The effect depends on whether the model is a reasoning model.
`safety_identifier`	string	No	A stable identifier for your end user, for safety and abuse detection. Pass a hashed user ID.
`metadata`	object	No	Custom key-value pairs attached to the request.
`stream`	boolean	No	Whether to stream the result. Default `false`.
`user`	string	No	Legacy alias for `safety_identifier`. When both are present, `safety_identifier` wins.

Input items

When input is a string, it's treated as one user message. When it's an array, each element is an input item with a type field:

type	Fields	Notes
`message`	`role`, `content`	A message. `role` is `user`, `assistant`, `system`, or `developer`; `content` is a string or an array of content blocks.
`function_call`	`call_id`, `name`, `arguments`	A record of a function call. `arguments` is a JSON string.
`function_call_output`	`call_id`, `output`	The result of running a function; `call_id` points at the corresponding `function_call`.

When a message's content is an array, these content blocks are supported:

type	Fields	Notes
`input_text`	`text`	Text input.
`input_image`	`image_url`, `detail`	Image input. `image_url` can be a public image URL or a `data:image/...;base64,...` data URL.
`input_file`	`file_id` or `file_url`	File input; supported on some models only.

Function tools

Declare functions the model can call via the tools field. The model returns a structured call request when needed.

{
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      }
    }
  ]
}

Field	Type	Required	Notes
`type`	string	Yes	Tool type; currently `function`.
`name`	string	Yes	The function name.
`description`	string	No	What the function does. A clear description helps the model decide when to call it.
`parameters`	object	No	JSON Schema for the function's parameters.
`strict`	boolean	No	Whether to require the model to generate arguments strictly matching the schema.

The following fields — used for multi-turn state and other advanced behavior — aren't part of CrossModel's official support surface yet. Whether they work depends on the model: some accept them, others return an unsupported_responses_feature error. For cross-model portability, avoid relying on them: previous_response_id, conversation, store, background, include, prompt, prompt_cache_key, prompt_cache_retention, context_management, max_tool_calls, service_tier, verbosity, stream_options, parallel_tool_calls.

Example request

curl https://api.crossmodel.ai/v1/responses \
  -H "Authorization: Bearer cm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "instructions": "You are a helpful assistant.",
    "input": "Hello!"
  }'

Response

A non-streaming request returns a response object.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "openai/gpt-5-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "Hello! How can I help?" }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 14,
    "total_tokens": 32
  }
}

Field	Type	Notes
`id`	string	A unique ID for this response.
`object`	string	Always `response`.
`status`	string	The response status; `completed` on success.
`model`	string	The model ID used for this request.
`output`	array	The generated output items.
`usage`	object	Token usage for this request, used for billing.

Output items

Each element of output is an item with a type field:

type	Fields	Notes
`message`	`id`, `role`, `status`, `content`	A generated message. `content` is an array of `output_text` blocks.
`function_call`	`id`, `call_id`, `name`, `arguments`, `status`	A function call issued by the model. `arguments` is a JSON string.

The usage object

Field	Type	Notes
`input_tokens`	integer	Input tokens.
`output_tokens`	integer	Output tokens.
`input_tokens_details.cached_tokens`	integer	Input tokens that hit the cache.
`output_tokens_details.reasoning_tokens`	integer	Tokens spent on reasoning.
`total_tokens`	integer	Input plus output tokens.

Streaming response

Set stream to true and the endpoint returns text/event-stream. Each event starts with data: and carries an event object with a type field:

Event	Notes
`response.created`	The response begins.
`response.output_item.added`	A new output item is added.
`response.output_text.delta`	An incremental piece of text.
`response.function_call_arguments.delta`	An incremental piece of function-call arguments.
`response.output_item.done`	An output item is complete.
`response.completed`	The response ends, carrying the full `output` and `usage`.

The stream ends with a response.completed event.

curl https://api.crossmodel.ai/v1/responses \
  -H "Authorization: Bearer cm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "input": "Hi",
    "stream": true
  }'

Errors

Errors use one shared format:

{
  "error": {
    "message": "Responses field 'store' is not supported in this release.",
    "type": "invalid_request_error",
    "param": "store",
    "code": "unsupported_responses_feature"
  }
}

HTTP status	`type`	Common `code`	Notes
`400`	`invalid_request_error`	`invalid_json`, `invalid_responses_input`, `unsupported_responses_feature`	Malformed body JSON, `input` structure, or fields.
`401`	`authentication_error`	`missing_api_key`, `invalid_api_key`	API key missing or invalid.
`402`	`billing_error`	`insufficient_balance`	Account out of balance.
`404`	`invalid_request_error`	`model_not_found`	The requested model doesn't exist or is currently unavailable.
`429`	`rate_limit_error`	`rate_limit_exceeded`, `provider_rate_limited`	Too many requests — rate limited.
`502`	`provider_error`	`provider_error`	The model service returned an error or an abnormal response.
`503`	`api_error`	`model_unavailable`	Model temporarily unavailable — retry shortly.
`500`	`api_error`	`internal_error`	A CrossModel internal error.