> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.asi1.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.asi1.ai/_mcp/server. # Create a response POST https://api.asi1.ai/v1/responses Content-Type: application/json Creates a model response using the Responses API. Supports streaming (`stream: true`, server-sent events) and background mode (`background: true`). When streaming, each frame carries a named `event:` and a JSON `data:` payload, and the stream ends on a terminal event, one of `response.completed`, `response.failed` or `response.incomplete`; there is no `[DONE]` sentinel. If the run stalls, the stream can instead end on a `data:` line holding an `error` object. Lines starting with `:` are keep-alive comments. OpenAI-compatible, so existing Responses API code runs unmodified. Unrecognized fields are rejected with a 400 (`unknown_parameter`). Reference: https://docs.asi1.ai/api-reference/responses/create-a-response ## Authentication - `Authorization` header (bearer token, required) — Your ASI:One API key, sent as `Authorization: Bearer `. ## Request ### Body (application/json) This endpoint expects a ResponseRequest. - `model` (string, required) — The ASI:One model to use. - `input` (ResponseRequestInput, required) — Text, or a list of input items, to generate a response for. Content parts are `input_text`, `output_text` and `input_image`. An `input_image` takes an `image_url` as a `data:` base64 URI or an https URL from a supported host (`file_id` is not supported), and a message takes up to 10 images. - `instructions` (string, optional) — System/developer instructions inserted ahead of the input. - `stream` (boolean, optional, default: false) — If true, response events are streamed as server-sent events. - `background` (boolean, optional, default: false) — If true, run the response as a background task; poll it with the retrieve endpoint or stop it with cancel. Requires `store: true`. - `store` (boolean, optional, default: true) — Whether to persist the response so it can be retrieved by id. With `false`, the retrieve, cancel, delete and input items endpoints return a 404 for it. - `previous_response_id` (string, optional) — The id of a previous response to continue from. - `max_output_tokens` (integer, optional) — Upper bound on tokens generated for the response. - `temperature` (double, optional) — Sampling temperature. - `top_p` (double, optional) — Nucleus sampling probability mass. - `tools` (list of ResponseRequestToolsItems, optional) — A list of tools the model may call. Function tools can use the flat Responses shape or the nested Chat Completions shape, and can be grouped in a `namespace`. A `web_search` tool lets the model search the web. Other tool types are rejected with a 400. See the [Tool Calling guide](https://docs.asi1.ai/documentation/build-with-asi-one/tool-calling). - `tool_choice` (ResponseRequestToolChoice, optional) — Controls which (if any) tool is called. - `parallel_tool_calls` (boolean, optional) — Whether the model may call several tools in one turn. - `text` (ResponseRequestText, optional) — Output format configuration. `text.format` takes precedence over `response_format`. - `reasoning` (ResponseRequestReasoning, optional) — Reasoning configuration. See the [Reasoning guide](https://docs.asi1.ai/documentation/build-with-asi-one/reasoning). - `enable_thinking` (boolean, optional) — ASI:One extension. Turns reasoning on or off on asi1-mini. The other models always reason; there an explicit `false` selects the shallowest depth. Used when `reasoning.effort` is absent. See the [Reasoning guide](https://docs.asi1.ai/documentation/build-with-asi-one/reasoning). - `thinking_budget` (integer, optional) — ASI:One extension. The older way to size reasoning. On asi1 and asi1-ultra the value selects a depth rather than capping tokens. See the [Reasoning guide](https://docs.asi1.ai/documentation/build-with-asi-one/reasoning). - `metadata` (map from string to string, optional) — Up to 16 key-value string pairs attached to the response. ## Response ### 200 A response object, or an SSE stream of response events when `stream` is true. - `id` (string, optional) - `object` (string, optional) - `status` (enum, optional) — Lifecycle status. `queued` and `in_progress` mean the run is still going; `completed`, `failed`, `cancelled` and `incomplete` are terminal. - Allowed values: `queued`, `in_progress`, `completed`, `failed`, `cancelled`, `incomplete` - `model` (string, optional) - `output` (list of ResponseObjectOutputItems, optional) - `usage` (ResponseObjectUsage, optional, nullable) — Token usage for the response. Null on a response cancelled before it finished. ## Errors ### 400 Bad Request Error The request was malformed, or a parameter was missing or invalid. - `error` (ErrorError, required) ### 401 Unauthorized Error The API key is missing or invalid. - `error` (ErrorError, required) ### 402 Payment Required Error The organization's account is blocked. - `message` (string, optional) - `code` (integer, optional) - `data` (AccountBlockedErrorData, optional) ### 404 Not Found Error The requested model or resource does not exist. - `error` (ErrorError, required) ### 409 Conflict Error The `previous_response_id` refers to a response that has not finished. Wait for it to reach a terminal status, then retry. - `error` (ErrorError, required) ### 429 Too Many Requests Error The rate limit for your plan has been exceeded. `error.data` says which limit was reached, for example `axis`, `limit` and `current`, and for windowed limits also `window`, `model` and when it resets (`resets_at`). Retry after the number of seconds in the `Retry-After` header. - `error` (ErrorError, required) ### 500 Internal Server Error An unexpected error occurred while handling the request. - `error` (ErrorError, required) ### 502 Bad Gateway Error An upstream service failed while handling the request. - `error` (ErrorError, required) ### 503 Service Unavailable Error The service is briefly unavailable, for example during a deployment or when the model is at capacity (`server_overloaded`). Retry after the number of seconds in the `Retry-After` header, when present, or after a short wait. - `error` (ErrorError, required) ### 504 Gateway Timeout Error The model did not respond in time. Retry the request. - `error` (ErrorError, required) ## Types ### ResponseRequestInput Text, or a list of input items, to generate a response for. Content parts are `input_text`, `output_text` and `input_image`. An `input_image` takes an `image_url` as a `data:` base64 URI or an https URL from a supported host (`file_id` is not supported), and a message takes up to 10 images. - string - list of ResponseRequestInputOneOf1Items ### ResponseRequestToolsItems - ResponsesFunctionTool: ResponsesFunctionTool - FunctionTool: FunctionTool - WebSearchTool: WebSearchTool - NamespaceTool: NamespaceTool ### ResponseRequestToolChoice Controls which (if any) tool is called. - enum - Allowed values: `auto`, `none`, `required` - map from string to any ### ResponseRequestText Output format configuration. `text.format` takes precedence over `response_format`. - `format` (TextFormat, optional) — The flat output-format shape used by `/v1/responses`. An unrecognized `type` is rejected with a 400. ### ResponseRequestReasoning Reasoning configuration. See the [Reasoning guide](https://docs.asi1.ai/documentation/build-with-asi-one/reasoning). - `effort` (enum, optional) — How much the model may reason before answering. `none` disables reasoning on asi1-mini; the other models always reason, so there it selects the shallowest depth. Any value outside OpenAI's scale is rejected with a 400. - Allowed values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh` ### ResponseObjectOutputItems ### ResponseObjectUsage Token usage for the response. Null on a response cancelled before it finished. - `input_tokens` (integer, optional) - `input_tokens_details` (ResponseObjectUsageInputTokensDetails, optional) — Breakdown of the input tokens. - `output_tokens` (integer, optional) - `output_tokens_details` (ResponseObjectUsageOutputTokensDetails, optional) — Breakdown of the output tokens. - `total_tokens` (integer, optional) ### ErrorError - `message` (string, required) — A human-readable description of the problem. - `status` (integer, required) — The HTTP status code, repeated in the body so it is available on streamed errors. - `type` (string, optional) — The error category, derived from the status code. Usually one of `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, `server_error`. - `param` (string, optional, nullable) — The request field the error relates to, when it maps to one. Nested fields use dot notation, for example `messages.0.content`. - `code` (string, optional) — A stable machine-readable code, for example `invalid_api_key` or `model_not_found`. - `data` (map from string to any, optional) — Additional structured detail, when available. ### AccountBlockedErrorData - `reason` (string, optional) ### ResponseRequestInputOneOf1Items ### ResponsesFunctionTool The flat function-tool shape accepted on `/v1/responses`, where the function's fields sit at the top level. The nested `FunctionTool` shape is accepted here too. - `type` (enum, required) — Always `function`. - Allowed values: `function` - `name` (string, required) — Name of the function. The model uses this to refer to the call. - `description` (string, optional) — What the function does and when to use it. The model selects tools from this text, so it is worth writing carefully. - `parameters` (map from string to any, optional) — JSON Schema describing the function's arguments. - `strict` (boolean, optional) — Whether the model must follow the parameter schema exactly. Requires `additionalProperties: false` and every property listed in `required`. ### FunctionTool A function the model may call. Your code defines the schema and executes the call. - `type` (enum, required) — Always `function`. - Allowed values: `function` - `function` (FunctionToolFunction, required) ### WebSearchTool Lets the model search the web. At most one per request. See the [Web Search guide](https://docs.asi1.ai/documentation/build-with-asi-one/web-search). - `type` ("web_search", required) - `search_context_size` (enum, optional, default: medium) — How much search context the model uses. Other fields are rejected with a 400. - Allowed values: `low`, `medium`, `high` ### NamespaceTool A named group of function tools. - `type` ("namespace", required) - `name` (string, required) - `description` (string, required) — What the group is for, shown to the model. - `tools` (list of ResponsesFunctionTool, required) ### TextFormat The flat output-format shape used by `/v1/responses`. An unrecognized `type` is rejected with a 400. - Text or JSON object: Text or JSON object - JSON schema: JSON schema ### ResponseObjectUsageInputTokensDetails Breakdown of the input tokens. - `cached_tokens` (integer, optional) — Input tokens served from cache. These still count toward `input_tokens`. ### ResponseObjectUsageOutputTokensDetails Breakdown of the output tokens. - `reasoning_tokens` (integer, optional) — Tokens spent reasoning before answering. `0` when the model did not reason. ### FunctionToolFunction - `name` (string, required) — Name of the function. The model uses this to refer to the call. - `description` (string, optional) — What the function does and when to use it. The model selects tools from this text, so it is worth writing carefully. - `parameters` (map from string to any, optional) — JSON Schema describing the function's arguments. - `strict` (boolean, optional) — Whether the model must follow the parameter schema exactly. Requires `additionalProperties: false` and every property listed in `required`. ### Text or JSON object - `type` (enum, required) - Allowed values: `text`, `json_object` ### JSON schema - `type` (enum, required) - Allowed values: `json_schema` - `name` (string, required) — Name of the schema. Required when `type` is `json_schema`. - `description` (string, optional) — What the schema is for. - `schema` (map from string to any, optional) — The JSON Schema the reply must conform to. - `strict` (boolean, optional) — Whether the reply must match the schema exactly. ## Examples **Request** ```json { "model": "asi1", "input": "What can you do?", "stream": false } ``` **Response** ```json { "id": "resp_ffbdb0b00b324505b1a46b92d4e1f5d2", "object": "response", "status": "completed", "model": "asi1", "output": [ {} ], "usage": { "input_tokens": 1, "input_tokens_details": { "cached_tokens": 1 }, "output_tokens": 1, "output_tokens_details": { "reasoning_tokens": 1 }, "total_tokens": 1 } } ``` **SDK Code** ```python Responses_createAResponse_example import requests url = "https://api.asi1.ai/v1/responses" payload = { "model": "asi1", "input": "What can you do?", "stream": False } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Responses_createAResponse_example const url = 'https://api.asi1.ai/v1/responses'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"model":"asi1","input":"What can you do?","stream":false}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Responses_createAResponse_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.asi1.ai/v1/responses" payload := strings.NewReader("{\n \"model\": \"asi1\",\n \"input\": \"What can you do?\",\n \"stream\": false\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Responses_createAResponse_example require 'uri' require 'net/http' url = URI("https://api.asi1.ai/v1/responses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"asi1\",\n \"input\": \"What can you do?\",\n \"stream\": false\n}" response = http.request(request) puts response.read_body ``` ```java Responses_createAResponse_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.asi1.ai/v1/responses") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"model\": \"asi1\",\n \"input\": \"What can you do?\",\n \"stream\": false\n}") .asString(); ``` ```php Responses_createAResponse_example request('POST', 'https://api.asi1.ai/v1/responses', [ 'body' => '{ "model": "asi1", "input": "What can you do?", "stream": false }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Responses_createAResponse_example using RestSharp; var client = new RestClient("https://api.asi1.ai/v1/responses"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"asi1\",\n \"input\": \"What can you do?\",\n \"stream\": false\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Responses_createAResponse_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "model": "asi1", "input": "What can you do?", "stream": false ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.asi1.ai/v1/responses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```