threads, assistant api, create, retrieve, modify, delete-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

This topic describes the Thread class in the assistant API, including how to create, retrieve, modify, and delete threads.

Important

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

Sample code

curl --location 'https://dashscope.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 parameters

The response returns a thread object with the following additional fields:

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

SDK

Sample code

Python

import json
import os
from dashscope import Threads

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))

Java

import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.AssistantThread;
import com.alibaba.dashscope.threads.ThreadParam;
import com.alibaba.dashscope.threads.Threads;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Threads threads = new Threads();
        // We recommend that you set the API key as an environment variable. If not, replace the following line with apiKey("sk-xxx") using your Model Studio API key.
        AssistantThread assistantThread = threads.create(ThreadParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build());
    }
}

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.

Result

The 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

Sample code

curl --location 'https://dashscope.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 parameters

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

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

SDK

Sample code

Python

from dashscope import Threads
import os

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")
)

Java

import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.AssistantThread;
import com.alibaba.dashscope.threads.Threads;

public class Main {
    public static void main(String[] args) {
        Threads threads = new Threads();
        // Pass the thread_id and apiKey directly
        // We recommend that you set the API key as an environment variable. If not, replace the following line with apiKey("sk-xxx") using your Model Studio API key.
        AssistantThread assistantThread = threads.retrieve(
            "thread_id",
            System.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 parameters

Refer to the creation result.

Modify a thread

HTTP

Sample code

curl --location 'https://dashscope.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 parameters

The 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.

SDK

Sample code

Python

from dashscope import Threads
import os

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'}
)

Java

import java.util.Collections;
import com.alibaba.dashscope.common.UpdateMetadataParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.Threads;

public class AssistantGeneral {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Threads threads = new Threads();
        UpdateMetadataParam updateMetadataParam = UpdateMetadataParam.builder()
                .metadata(Collections.singletonMap("key", "value"))
                // We recommend that you set the API key as an environment variable. If not, replace the following line with apiKey("sk-xxx") and use your Model Studio API key.
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        threads.update("thread_id", updateMetadataParam);
    }
}

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 parameters

This operation is the same as the create operation.

Delete a thread

HTTP

Sample code

curl --location --request DELETE 'https://dashscope.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 parameters

The status of the thread after deletion.

SDK

Sample code

Python

from dashscope import Threads
import os

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")
)

Java

import com.alibaba.dashscope.common.DeletionStatus;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.Threads;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Threads threads = new Threads();
        // We recommend that you set the API key as an environment variable. If not, replace the following line with apiKey("sk-xxx") using your Model Studio API key.
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        DeletionStatus assistantThread = threads.delete("thread_id", apiKey);
    }
}

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.