Threads - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

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

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

Parameter	Description	Type	Required
messages	The messages passed to the thread.	Message class	No
metadata	Thread name	string	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
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))

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;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    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.

Sample response

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

{
    "account_id": "sk-6bddfc116de744c3aa1d66893cc87b20",
    "created_at": 1711338305031,
    "gmt_create": "2024-03-25 11:45:05",
    "gmt_update": "2024-03-25 11:45:05",
    "id": "thread_97934051-2c15-44bf-97de-310039d873f9",
    "is_deleted": false,
    "metadata": {},
    "object": "thread",
    "request_id": "982d4b9a-b982-9d53-9c79-a75b32f7168a",
    "status_code": 200
}

Response parameters

Field	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.
Creation Time	datetime	2024-03-22 17:12:31
GMT Modified	datetime	2024-03-22 17:12:31
code	str	The error code. This field is returned only when the request fails. This parameter is for Python only.
message	str	The error message. This field is returned only when the request fails. This parameter is for Python only.

Retrieve a thread

HTTP

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	Description	Type	Required
thread_id	The ID of the thread to retrieve.	str	Yes

Sample response

{
    "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: The thread ID.
request_id: The ID of the request.

SDK

Sample code

Python

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

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;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        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-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

Parameter	Description	Type	Required
thread_id	The thread ID to retrieve.	str	Yes
metadata	Thread name	dict	No

Sample response

{
    "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 response returns the modified thread object with the following additional fields:

id: thread_id
request_id: The request ID.

SDK

Sample code

Python

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

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;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    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") using your Model Studio API key.
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        threads.update("assistant_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-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	Description	Type	Required
id	The ID of the thread to retrieve	str	Yes

Sample response

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

Response parameters

The response returns an object that indicates the status of the delete operation.

SDK

Sample code

Python

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

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;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    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	Type	Description
id	str	The ID of the deleted object.
deleted	bool	Indicates whether the object was deleted.

Error codes

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