ListModels

Updated at:
Copy as MD

Queries the text models visible to the current caller for selection when setting a session model.

Operation description

  • For text sessions, pass ModelType=text and use MaxResults and NextToken for paging. Obtain the model identifier from Models[].Id and pass it as Params.modelId to SetAgentSessionModel.

  • Visibility in the model catalog does not mean the target session supports the model. After setting the model, refer to the return value of SetAgentSessionModel or the query result of GetAgentSessionModel.

  • ThinkingLevels and ThinkingLevel are used for optional thinking level configurations and do not affect the integration flow for selecting a model only.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ada:ListModels

list

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

MaxResults

integer

No

The maximum number of models to return per page. Valid values: 1 to 100. Explicitly specify this parameter.

20

NextToken

string

No

The pagination token returned from the previous page. Omit this parameter for the first page.

next-token-example

PageNumber

integer

No

The legacy pagination parameter for compatibility. The page number starts from 1. Use MaxResults and NextToken instead. Do not mix the two sets of pagination parameters.

1

PageSize

integer

No

The legacy pagination parameter for compatibility. The number of entries per page. Valid values: 1 to 100. Use MaxResults and NextToken instead. Do not mix the two sets of pagination parameters.

20

ModelType

string

No

Set to text for text sessions. If omitted, all visible models are queried.

Valid values:

  • text
  • audio

text

The call method is POST, and business parameters are located in query. The region is determined by the client configuration. The example only shows business parameters. Action, Version, identity, and signature are handled by the POP client.

All request parameters are top-level fields. During pagination, subsequent requests must keep ModelType consistent and pass the NextToken returned last time as is. This token cannot be constructed manually or reused across filter conditions. If no pagination parameters are passed, all models are returned.

PageNumber and PageSize are retained for compatibility with legacy calls. Use MaxResults and NextToken instead. Do not mix the two sets of pagination parameters.

Request example

{
  "ModelType": "text",
  "MaxResults": 20
}

Response elements

Element

Type

Description

Example

object

Models

array<object>

The array of model structures. For nested fields, refer to the supplementary description of response parameters.

[{"Id":"text-model-example","Object":"model","Created":1793491200,"OwnedBy":"provider-example","DisplayName":"Sample text model","Capabilities":{"InputModalities":["text"]},"CreditsCoefficient":"2.5","ThinkingLevels":["off","low","medium","high"],"ThinkingLevel":"off"}]

array<object>

Id

string

The model identifier. Used as Params.modelId for SetAgentSessionModel. Use the actual returned value.

text-model-example

Object

string

The object type. Fixed to model.

model

Created

integer

The time when the model was created. It is a UNIX timestamp in seconds.

1793491200

OwnedBy

string

The identifier of the model provider.

provider-example

DisplayName

string

The display name of the model. Do not pass it as the model identifier.

Sample text model

CreditsCoefficient

string

The credit coefficient of the model, returned as a decimal string. Not returned if not configured.

2.5

Capabilities

object

The model capabilities structure.

{"InputModalities":["text"]}

InputModalities

array

The supported input modalities. For text sessions, select a model that includes text.

["text"]

string

An input modality supported by the model. text indicates text input.

text

ContextWindow deprecated

integer

[Deprecated] The legacy compatibility field. It is no longer returned. Do not use it as a dependency for integration.

32768

MaxContextWindow deprecated

integer

[Deprecated] The legacy compatibility field. It is no longer returned. Do not use it as a dependency for integration.

131072

SupportsThinking deprecated

integer

[Deprecated] The legacy compatibility field. It is no longer returned. Use ThinkingLevels instead.

1

ThinkingMode deprecated

integer

[Deprecated] The legacy compatibility field. It is no longer returned. Use ThinkingLevel instead.

0

ThinkingLevels

array

The thinking levels supported by the model. An empty array does not mean all levels are supported. The target session still needs to be verified.

["off","low","medium","high"]

string

A thinking level supported by the model. Refer to the model catalog return results for specific values.

off

ThinkingLevel

string

The default thinking level in the model catalog. It does not represent the current value of the session. Query the current value by using GetAgentSessionModel.

Valid values:

  • off
  • low
  • medium
  • high

off

Total

integer

The total number of models that meet the filter conditions.

1

MaxResults

integer

The maximum number of results used for this pagination. If not paginated, it is the total number of results. It is not the actual number of entries returned on this page.

20

NextToken

string

The token for the next page. An empty value indicates that there is no next page.

next-token-example

RequestId

string

The ID of the request. It is used for troubleshooting.

0A1B2C3D-4E5F-6789-ABCD-EF0123456789

The Models[].Id in the model catalog is used to submit the selection, and the modelId returned by the session indicates the actual effective configuration. The two may be different. The caller must save the setting result and verify it against the modelId returned by subsequent GetAgentSessionModel calls. Do not assume failure simply because the catalog ID and the session ID string are not equal, and do not manually concatenate or remove the provider suffix.

Models is an array of model structures, and each item is a Model. Capabilities is a ModelCapabilities structure. The following field names are the names returned by POP and are case-sensitive. Pass Models[].Id as is to Params.modelId of the session API. The field names inside the session API do not change with this API.

NameTypeDescriptionExample value
Models[].IdstringThe model identifier. Used as Params.modelId for SetAgentSessionModel. Use the actual returned value.text-model-example
Models[].ObjectstringThe object type. Fixed to model.model
Models[].Createdint64The time when the model was created. It is a UNIX timestamp in seconds.1793491200
Models[].OwnedBystringThe identifier of the model provider.provider-example
Models[].DisplayNamestringThe display name of the model. Do not pass it as the model identifier.Sample text model
Models[].CapabilitiesobjectThe model capabilities structure.{"InputModalities":["text"]}
Models[].Capabilities.InputModalitiesarray<string>The supported input modalities. For text sessions, select a model that includes text.["text"]
Models[].CreditsCoefficientstringThe credit coefficient of the model, returned as a decimal string. Not returned if not configured.2.5
Models[].ThinkingLevelsarray<string>The thinking levels supported by the model. An empty array does not mean all levels are supported. The target session still needs to be verified.["off","low","medium","high"]
Models[].ThinkingLevelstringThe default thinking level in the model catalog. It does not represent the current value of the session. Query the current value by using GetAgentSessionModel.off
Models[].ContextWindowint64[Deprecated] The legacy compatibility field. It is no longer returned. Do not use it as a dependency for integration.32768
Models[].MaxContextWindowint64[Deprecated] The legacy compatibility field. It is no longer returned. Do not use it as a dependency for integration.131072
Models[].SupportsThinkingint32[Deprecated] The legacy compatibility field. It is no longer returned. Use ThinkingLevels instead.1
Models[].ThinkingModeint32[Deprecated] The legacy compatibility field. It is no longer returned. Use ThinkingLevel instead.0

If you do not need to configure the thinking level, use only the model identifier. If configuration is required, refer to the returned level options and read the actual effective value after setting. Optional fields may not be returned. Do not infer the current session configuration based on the default values in the model catalog.

Normal response example

The model identifiers in the example are for illustration only. Use the actual queried model identifiers when making calls.

{
  "Models": [
    {
      "Id": "text-model-example",
      "Object": "model",
      "Created": 1793491200,
      "OwnedBy": "provider-example",
      "DisplayName": "Sample text model",
      "Capabilities": {
        "InputModalities": [
          "text"
        ]
      },
      "CreditsCoefficient": "2.5",
      "ThinkingLevels": [
        "off",
        "low",
        "medium",
        "high"
      ],
      "ThinkingLevel": "off"
    }
  ],
  "Total": 1,
  "MaxResults": 20,
  "NextToken": "",
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Examples

Success response

JSON format

{
  "Models": [
    {
      "Id": "text-model-example",
      "Object": "model",
      "Created": 1793491200,
      "OwnedBy": "provider-example",
      "DisplayName": "Sample text model",
      "CreditsCoefficient": "2.5",
      "Capabilities": {
        "InputModalities": [
          "text"
        ]
      },
      "ContextWindow": 32768,
      "MaxContextWindow": 131072,
      "SupportsThinking": 1,
      "ThinkingMode": 0,
      "ThinkingLevels": [
        "off"
      ],
      "ThinkingLevel": "off"
    }
  ],
  "Total": 1,
  "MaxResults": 20,
  "NextToken": "next-token-example",
  "RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified parameter is invalid.
422 InvalidParameter The specified parameter is invalid.
401 Unauthenticated Authentication required.
403 Forbidden You are not authorized to operate the model catalog.

See Error CodesError Codes for a complete list.

Release notes

See Release NotesRelease Notes for a complete list.