Threads (Deprecated) - Alibaba Cloud Model Studio

The Assistant API is being deprecated. Migrate to the Responses API as an alternative. The Responses API includes multiple built-in tools and supports multi-turn context management.

Overview: For more information about the features and basic usage of the assistant API, see Assistant API overview.

Retention period: All Thread instances are stored on the Alibaba Cloud Model Studio server and do not expire. You can use the thread ID to retrieve context information.

Function name	Type
create	Creates a Thread class.
retrieve	Retrieves a Thread class.
update	Modifies a Thread class.
delete	Deletes a Thread class.

Create a thread

HTTP
SDK

Sample code

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "messages": [
        {
            "role": "user",
            "content": "hello"
        }
    ]
}'

Request parameters

Input parameter name	Input parameter descriptions	Type	Required
messages	The messages passed to the thread.	Message class	No
metadata	Thread name	object	No

Response

{
    "id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
    "object": "thread",
    "created_at": 1711448377850,
    "metadata": {},
    "request_id": "dd9489ec-dbdb-95d4-9ff8-cfe29b61db27"
}

Response parametersThe response returns a thread object with the following additional fields:

id: The thread ID.
request_id: The request ID.

Sample code

import json
from dashscope import Threads
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Threads.create(
    # We recommend that you set the API key as an environment variable. If not, replace the following line with api_key="sk-xxx" using your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    messages=[{"role": "user", "content": "How does AI work? Explain it in simple terms."}]
)
print(json.dumps(thread, default=lambda o: o.__dict__, sort_keys=True, indent=4))

Request parameters

Parameter	Type	Default value	Description
messages	List[Dict]	None	The initial messages of the thread.
metadata	Dict	None	Key-value pairs to associate with the thread.
workspace	str	None	The workspace ID of Alibaba Cloud Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	str	None	The API key for Alibaba Cloud Model Studio. We recommend that you configure the API key as an environment variable.

ResultThe result is a Thread object. The following code shows the object in JSON format:

{
    "created_at": 1711338305031,
    "id": "thread_97934051-2c15-44bf-97de-310039d873f9",
    "metadata": {},
    "object": "thread",
    "request_id": "982d4b9a-b982-9d53-9c79-a75b32f7168a",
    "status_code": 200
}

Output parameters

Field name	Type	Description
status_code	int	The HTTP status code. A value of 200 indicates that the call is successful. Other values indicate that the call failed.
id	str	The thread ID, which is a UUID string.
metadata	Dict	The key-value pairs associated with the thread.
created_at	timestamp	The time when the thread was created.
code	str	The error code that is returned if the request fails. This parameter is not returned if the request is successful. Python only
message	str	The error message. This field is returned only when the request fails. Python only

Retrieve a thread

HTTP
SDK

Sample code

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request parameters

Parameter Name	Parameter description	Type	Required
thread_id	The ID of the thread to retrieve.	str	Yes

Result

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread",
    "created_at": 1711507920700,
    "metadata": {},
    "request_id": "4d4e73ad-15fb-96ac-9262-0643a0fdb5ca"
}

Response parametersThe response contains the retrieved thread object, which includes the following additional fields:

ID: Thread ID
request_id: The ID of the request.

Sample code

from dashscope import Threads
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Threads.retrieve(
    'thread_id',
    # We recommend that you set the API key as an environment variable. If not, replace the following line with api_key="sk-xxx" using your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

Request parameters

Parameter	Type	Default value	Description
thread_id	str	-	The ID of the thread to query.
workspace	str	None	The workspace ID of Alibaba Cloud Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	str	None	The API key for Alibaba Cloud Model Studio. We recommend that you configure the API key as an environment variable.

Response parametersRefer to the creation result.

Modify a thread

HTTP
SDK

Sample code

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "metadata": {
        "modified": "true",
        "user": "abc123"
    }
}'

Request parameters

Input Parameter Name	Input Parameter Descriptions	Type	Required
thread_id	The ID of the thread to modify.	str	Yes
metadata	Thread name	dict	No

Result

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread",
    "created_at": 1711507920700,
    "metadata": {
        "modified": "true",
        "user": "abc123"
    },
    "request_id": "a9ad63fa-b884-94be-9ec6-5000882de3c4"
}

Response parametersThe output contains the retrieved thread class and additional fields that are not specified in the user-provided parameters:

id: thread_id
request_id: The request ID.

Sample code

from dashscope import Threads
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Threads.update(
    'thread_id',
    # We recommend that you set the API key as an environment variable. If not, replace the following line with api_key="sk-xxx" using your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    metadata={'key': 'value'}
)

Request parameters

Parameter	Type	Default value	Description
thread_id	str	-	The ID of the thread to update.
metadata	Dict	None	The information to associate with the thread.
workspace	str	None	The workspace ID of Alibaba Cloud Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	str	None	The API key for Alibaba Cloud Model Studio. We recommend that you configure the API key as an environment variable.

Response parametersThis operation is the same as the create operation.

Delete a thread

HTTP
SDK

Sample code

curl --location --request DELETE 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request parameters

Input Parameter Name	Description	Type	Required
id	The ID of the thread to delete	str	Yes

Response

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread.deleted",
    "deleted": true,
    "request_id": "b4edb7b8-5855-9787-b5c3-0374ee2b3b2c"
}

Response parametersThe status of the thread after deletion.

Sample code

from dashscope import Threads
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Threads.delete(
    'thread_id',
    # We recommend that you set the API key as an environment variable. If not, replace the following line with api_key="sk-xxx" using your Model Studio API key.
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

Request parameters

Parameter	Type	Default value	Description
thread_id	str	-	The ID of the thread to delete.
workspace	str	None	The workspace ID of Alibaba Cloud Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	str	None	The API key for Alibaba Cloud Model Studio. We recommend that you configure the API key as an environment variable.

Response parameters

Field Name	Type	Description
id	str	The ID of the deleted object.
deleted	bool	Confirm Deletion

Error codes

If a model call fails and an error message is returned, see Error codes for troubleshooting.

​Create a thread

​Retrieve a thread

​Modify a thread

​Delete a thread

​Error codes

Create a thread

Retrieve a thread

Modify a thread

Delete a thread

Error codes