Skip to main content
POST
/
v1
/
responses

​
Authorization

  • Auth Type: Bearer Auth (In: header)
  • Format: Authorization: Bearer <YOUR_API_KEY>
  • Description: Use Bearer <YOUR_API_KEY>. Format: Authorization: Bearer sk-xxxxxx.
  • API Key: where API Key is your AGCloud API KEY

​
Request Body

​
Core Parameters

FieldTypeRequiredRangeDescription
modelstring✅-Model ID used to generate the response.
inputarray<object>✅-The input content.
>input.roleenum✅user
assistant
system
developer		The role of the message sender. Can be user model.
>input.contentstring|array<object>✅-A text input to the model when string; a list of one or many input items to the model, containing different content types when array. See Multimodal Input for details.

​
Content Structure

FieldTypeRequiredRangeDescription
typestring✅input_text
input_image
input_file		Identifies the content block type for multimodal input.
textstring--The text input content.
file_idstring--The ID of the file to be sent to the model.
detailstring-low
high
auto		The detail level of the image to be sent to the model. One of high, low, or auto. Defaults to auto. Only required when type=input_image. Default auto.
image_urlstring--The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. Only required when type=input_image.
file_urlstring--The URL of the file to be sent to the model. Only required when type=input_file.
file_datastring--The content of the file to be sent to the model. Only required when type=input_file.
filenamestring--The name of the file to be sent to the model. Only required when type=input_file.
{
  "role": "user",
  "content": [
    {
      "type": "input_text",
      "text": "Who are you?"
    }
  ]
}

​
Advanced Parameters

FieldTypeRequiredRangeDescription
streamboolean--Whether to stream the response back incrementally. Defaults false.
max_output_tokensinternet--An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
reasoningobject--Configuration options for reasoning models (gpt-5 and o-series models only).
>reasoning.effortenum-none
minimal
low
medium
high
xhigh		Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. See Model-Specific Reasoning Configurations for details.
>reasoning.summaryenum-auto
concise
detailed		A summary of the reasoning performed by the model. Useful for debugging and understanding the model’s reasoning process.
toolsarray<object>--A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. See Tools Parameters for details.

​
Tools Parameters

{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      },
      "search_context_size": "low",
      "user_location": {
        "city": "San Francisco",
        "country": "US",
        "region": "California",
        "timezone": "America/Los_Angeles",
        "type": "approximate"
      }
    }
  ]
}
FieldTypeRequiredRangeDescription
typeenum-web_search
web_search_2025_08_26		The type of the web search tool.
filterobject--Filters for the search.
>filter.allowed_domainsarray<string>--Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well.
search_context_sizeenum-low
medium
high		High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
user_locationobject--The approximate location of the user.
>user_location.citystring--Free text input for the city of the user, e.g. San Francisco.
>user_location.countrystring--The two-letter ISO country code of the user, e.g. US.
>user_location.regionstring--Free text input for the region of the user, e.g. California.
>user_location.timezonestring--The IANA timezone of the user, e.g. America/Los_Angeles.
>user_location.typestring-approximateThe type of location approximation. Always approximate.

​
Model-Specific Reasoning.effort Configurations

Constrains effort on reasoning for reasoning models. Currently supported values are none, minimal, low, medium, high, and xhigh. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
  • gpt-5.1 defaults to none, which does not perform reasoning. The supported reasoning values for gpt-5.1 are none, low, medium, and high. Tool calls are supported for all reasoning values in gpt-5.1.
  • All models before gpt-5.1 default to medium reasoning effort, and do not support none.
  • The gpt-5-pro model defaults to (and only supports) high reasoning effort.
  • xhigh is supported for all models after gpt-5.1-codex-max.