# OpenAI-compatible - Conversations

> Manually managing message lists for conversations that span multiple devices or have long interruptions can lead to context loss. Alibaba Cloud Model Studio provides an OpenAI-compatible Conversations API that you can use with the Responses API to automatically inject historical context. This eliminates the need for manual message synchronization and ensures conversational continuity across different scenarios and devices.

## Create conversation <span id="h2-create-conversation" />

Creates a new conversation. You can optionally include initial message items.

<strong>North China 2 (Beijing): POST</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations`

<strong>Singapore: POST</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations`

<Tip>
  The legacy URL path `/api/v2/apps/protocols/compatible-mode/v1/conversations` will soon be deprecated. Migrate to the new path `/compatible-mode/v1/conversations` as soon as possible.
</Tip>

<Tip>
  Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. <strong>The new dedicated domains deliver superior performance and higher stability for inference requests</strong>. We recommend migrating to the new domains:

  - China (Beijing): from `https://dashscope.aliyuncs.com` to `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`
  - Singapore: from `https://dashscope-intl.aliyuncs.com` to `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`

  `{WorkspaceId}` is your workspace ID, which can be found on the <strong>Workspace Details</strong> page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.
</Tip>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>items</strong>`array` (Optional)

        A list of up to 20 initial message items.

        <Accordion title="Properties" defaultOpen>
          <strong>type</strong>`string`<strong>(Required)</strong>

          The message type. Only `message` is supported.

          <strong>role</strong>`string`<strong>(Required)</strong>

          The role of the message. Instructions from the `system` and `developer` roles have a higher priority than instructions from the `user` role. The `assistant` role indicates messages that were generated by the model in previous interactions. Valid values are `user`, `assistant`, `system`, and `developer`.

          <strong>content</strong>`string or array`<strong>(Required)</strong>

          The message content. This parameter supports plain text strings or structured content lists, such as ResponseInputText object arrays. The list format can include various content types, such as text.
        </Accordion>

        <strong>metadata</strong>`object` (Optional)

        The conversation metadata. Use this parameter to store additional conversation information in a structured format. Specify up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          conversation = client.conversations.create(
              metadata={"topic": "demo"},
              items=[
                  {"type": "message", "role": "system", "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."}
              ]
          )
          print(conversation)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const conversation = await client.conversations.create({
              metadata: { topic: "demo" },
              items: [
                  {
                      type: "message",
                      role: "system",
                      content: "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
                  }
              ]
          });
          console.log(conversation);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations' \
          --header 'Content-Type: application/json' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
          --data '{
              "metadata": {
                  "topic": "demo"
              },
              "items": [
                  {
                      "type": "message",
                      "role": "system",
                      "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
                  }
              ]
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-create-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>created\_at</strong>`integer`

        The Unix timestamp in milliseconds that indicates when the conversation was created.

        <strong>id</strong>`string`

        The unique ID of the conversation.

        <strong>metadata</strong>`object`

        The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

        <strong>object</strong>`string`

        The object type. The value is fixed as `conversation`.
      </td>

      <td>
        ```json
        {
            "created_at": 1771316949128,
            "id": "conv_xxx",
            "metadata": {
                "topic": "demo"
            },
            "object": "conversation"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Retrieve conversation <span id="h2-retrieve-conversation" />

Retrieves information for a specified conversation.

<strong>North China 2 (Beijing): GET</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<strong>Singapore: GET</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The conversation ID.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          conversation = client.conversations.retrieve("conv_xxx")
          print(conversation)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const conversation = await client.conversations.retrieve(
              "conv_xxx"
          );
          console.log(conversation);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-retrieve-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>created\_at</strong>`integer`

        The Unix timestamp in milliseconds that indicates when the conversation was created.

        <strong>id</strong>`string`

        The unique ID of the conversation.

        <strong>metadata</strong>`object`

        The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

        <strong>object</strong>`string`

        The object type. The value is fixed as `conversation`.
      </td>

      <td>
        ```json
        {
            "created_at": 1771316949128,
            "id": "conv_xxx",
            "metadata": {
                "topic": "demo"
            },
            "object": "conversation"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Update conversation <span id="h2-update-conversation" />

Updates the metadata for a conversation.

<strong>North China 2 (Beijing): POST</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<strong>Singapore: POST</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the conversation.

        <strong>metadata</strong>`object`<strong>(Required)</strong>

        The conversation metadata. This parameter completely overwrites the existing metadata. Specify up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          updated = client.conversations.update(
              "conv_xxx",
              metadata={"topic": "update"}
          )
          print(updated)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const updated = await client.conversations.update(
              "conv_xxx",
              { metadata: { topic: "update" } }
          );
          console.log(updated);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
          --header 'Content-Type: application/json' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
          --data '{
              "metadata": {
                  "topic": "update"
              }
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-update-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>created\_at</strong>`integer`

        The Unix timestamp in milliseconds that indicates when the conversation was created.

        <strong>id</strong>`string`

        The unique ID of the conversation.

        <strong>metadata</strong>`object`

        The conversation metadata. This parameter stores additional information as key-value pairs. It can contain up to 16 pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.

        <strong>object</strong>`string`

        The object type. The value is fixed as `conversation`.
      </td>

      <td>
        ```json
        {
            "created_at": 1771318152759,
            "id": "conv_xxx",
            "metadata": {
                "topic": "update"
            },
            "object": "conversation"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Delete conversation <span id="h2-delete-conversation" />

Deletes a specified conversation. Message items within the conversation are not deleted.

<strong>North China 2 (Beijing): DELETE</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<strong>Singapore: DELETE</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The conversation ID.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          result = client.conversations.delete("conv_xxx")
          print(result)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const result = await client.conversations.del(
              "conv_xxx"
          );
          console.log(result);
          ```

          ```bash cURL
          curl --location --request DELETE 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-delete-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>deleted</strong>`boolean`

        Indicates whether the deletion was successful.

        <strong>id</strong>`string`

        The ID of the deleted conversation.

        <strong>object</strong>`string`

        The object type. The value is fixed as `conversation.deleted`.
      </td>

      <td>
        ```json
        {
            "deleted": true,
            "id": "conv_xxx",
            "object": "conversation.deleted"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Create items <span id="h2-create-items" />

Adds message items to a specified conversation.

<strong>North China 2 (Beijing): POST</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items`

<strong>Singapore: POST</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the conversation.

        <strong>items</strong>`array`<strong>(Required)</strong>

        A list of message items. You can add up to 20 items at a time.

        <Accordion title="Properties" defaultOpen>
          <strong>type</strong>`string`<strong>(Required)</strong>

          The message type. Only `message` is supported.

          <strong>role</strong>`string`<strong>(Required)</strong>

          The role of the message. Instructions from the `system` and `developer` roles have a higher priority than instructions from the `user` role. The `assistant` role indicates messages that were generated by the model in previous interactions. Valid values are `user`, `assistant`, `system`, and `developer`.

          <strong>content</strong>`string or array`<strong>(Required)</strong>

          The message content. This parameter supports plain text strings or structured content lists, such as ResponseInputText object arrays. The list format can include various content types, such as text.
        </Accordion>
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          items = client.conversations.items.create(
              "conv_xxx",
              items=[
                  {
                      "type": "message",
                      "role": "user",
                      "content": [{"type": "input_text", "text": "Alice's major is teacher education"}],
                  }
              ],
          )
          print(items.data)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const items = await client.conversations.items.create(
              "conv_xxx",
              {
                  items: [
                      {
                          type: "message",
                          role: "user",
                          content: [{ type: "input_text", text: "Alice's major is teacher education" }]
                      }
                  ]
              }
          );
          console.log(items.data);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items' \
          --header 'Content-Type: application/json' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
          --data '{
              "items": [
                  {
                      "type": "message",
                      "role": "user",
                      "content": [{
                          "type": "input_text",
                          "text": "Alice's major is teacher education"
                      }]
                  }
              ]
          }'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-create-items-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>data</strong>`array[object]`

        A list of the created message items.

        <Accordion title="Properties" defaultOpen>
          <strong>id</strong>`string`

          The unique ID of the message item.

          <strong>content</strong>`string or array`

          The message content. This can be a plain text string or a structured content list, such as a ResponseInputText object array.

          <strong>role</strong>`string`

          The role of the message. Valid values are `user`, `assistant`, `system`, and `developer`.

          <strong>status</strong>`string`

          The processing status of the message. Valid values are `in_progress`, `completed`, and `incomplete`.

          <strong>type</strong>`string`

          The type of the message item. The value is fixed as `message`.
        </Accordion>

        <strong>first\_id</strong>`string`

        The ID of the first message item in the list.

        <strong>has\_more</strong>`boolean`

        Indicates whether more data is available.

        <strong>last\_id</strong>`string`

        The ID of the last message item in the list.
      </td>

      <td>
        ```json
        {
            "data": [
                {
                    "content": [
                        {
                            "text": "Alice's major is teacher education",
                            "type": "input_text"
                        }
                    ],
                    "id": "msg_xxx",
                    "role": "user",
                    "status": "completed",
                    "type": "message"
                }
            ],
            "first_id": "msg_xxx",
            "has_more": false,
            "last_id": "msg_xxx"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## List items <span id="h2-list-items" />

Lists all message items in a conversation.

<strong>North China 2 (Beijing): GET</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items`

<strong>Singapore: GET</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the conversation.

        <strong>after</strong>`string` (Optional)

        The pagination cursor. Returns only message items created after the specified message ID.

        <strong>order</strong>`string` (Optional)

        The sort order. Valid values are `asc` for ascending and `desc` for descending. The default value is `desc`.

        <strong>limit</strong>`integer` (Optional)

        The number of items to return. The value must be an integer from 1 to 100. The default value is 20.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          items = client.conversations.items.list("conv_xxx")
          print(items.data)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const items = await client.conversations.items.list(
              "conv_xxx"
          );
          console.log(items.data);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items?limit=10&order=asc' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-list-items-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>data</strong>`array[object]`

        A list of the message items.

        <Accordion title="Properties" defaultOpen>
          <strong>id</strong>`string`

          The unique ID of the message item.

          <strong>content</strong>`string or array`

          The message content. This can be a plain text string or a structured content list, such as a ResponseInputText object array.

          <strong>role</strong>`string`

          The role of the message. Valid values are `user`, `assistant`, `system`, and `developer`.

          <strong>status</strong>`string`

          The processing status of the message. Valid values are `in_progress`, `completed`, and `incomplete`.

          <strong>type</strong>`string`

          The type of the message item. The value is fixed as `message`.
        </Accordion>

        <strong>first\_id</strong>`string`

        The ID of the first message item in the list.

        <strong>has\_more</strong>`boolean`

        Indicates whether more data is available.

        <strong>last\_id</strong>`string`

        The ID of the last message item in the list.

        <strong>object</strong>`string`

        The object type. The value is fixed as `list`.
      </td>

      <td>
        ```json expandable
        {
            "data": [
                {
                    "content": [
                        {
                            "text": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess.",
                            "type": "input_text"
                        }
                    ],
                    "id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
                    "role": "user",
                    "status": "completed",
                    "type": "message"
                },
                {
                    "content": [
                        {
                            "text": "Alice's best friend is Bob",
                            "type": "input_text"
                        }
                    ],
                    "id": "msg_288594f6-6ef1-4519-94d4-a545ca311828",
                    "role": "user",
                    "status": "completed",
                    "type": "message"
                }
            ],
            "first_id": "msg_7639f8f6-484b-454a-8125-96a3f40eb9e8",
            "has_more": false,
            "last_id": "msg_288594f6-6ef1-4519-94d4-a545ca311828",
            "object": "list"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Retrieve item <span id="h2-retrieve-item" />

Retrieves the details for a specified message item.

<strong>North China 2 (Beijing): GET</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}`

<strong>Singapore: GET</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the conversation.

        <strong>item\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the message item.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          item = client.conversations.items.retrieve(
              "msg_xxx",
              conversation_id="conv_xxx"
          )
          print(item)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const item = await client.conversations.items.retrieve(
              "msg_xxx",
              { conversation_id: "conv_xxx" }
          );
          console.log(item);
          ```

          ```bash cURL
          curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-retrieve-item-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>content</strong>`array[object]`

        A list of message content that contains one or more content objects.

        <Accordion title="Properties" defaultOpen>
          <strong>type</strong>`string`

          The content type, such as `input_text` for user input text or `output_text` for model output text.

          <strong>text</strong>`string`

          The text content.
        </Accordion>

        <strong>id</strong>`string`

        The unique ID of the message item.

        <strong>role</strong>`string`

        The role of the message. Valid values are `user`, `assistant`, `system`, and `developer`.

        <strong>status</strong>`string`

        The processing status of the message. Valid values are `in_progress`, `completed`, and `incomplete`.

        <strong>type</strong>`string`

        The type of the message item. The value is fixed as `message`.
      </td>

      <td>
        ```json
        {
            "content": [
                {
                    "text": "Alice's major is teacher education",
                    "type": "input_text"
                }
            ],
            "id": "msg_xxx",
            "role": "user",
            "status": "completed",
            "type": "message"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Delete item <span id="h2-delete-item" />

Deletes a specified message item.

<strong>North China 2 (Beijing): DELETE</strong> `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}`

<strong>Singapore: DELETE</strong> `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}`

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>conversation\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the conversation.

        <strong>item\_id</strong>`string`<strong>(Required, Path)</strong>

        The ID of the message item.
      </td>

      <td>
        <CodeGroup dropdown>
          ```python Python
          import os
          from openai import OpenAI

          client = OpenAI(
              api_key=os.getenv("DASHSCOPE_API_KEY"),
              base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          )

          result = client.conversations.items.delete(
              "msg_xxx",
              conversation_id="conv_xxx"
          )
          print(result)
          ```

          ```javascript Node.js
          import OpenAI from "openai";

          const client = new OpenAI({
              apiKey: process.env.DASHSCOPE_API_KEY,
              baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
          });

          const result = await client.conversations.items.del(
              "msg_xxx",
              { conversation_id: "conv_xxx" }
          );
          console.log(result);
          ```

          ```bash cURL
          curl --location --request DELETE 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx/items/msg_xxx' \
          --header 'Authorization: Bearer $DASHSCOPE_API_KEY'
          ```
        </CodeGroup>
      </td>
    </tr>
  </tbody>
</table>

### Response parameters <span id="h3-delete-item-response" />

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        <strong>deleted</strong>`boolean`

        Indicates whether the item was successfully deleted.

        <strong>id</strong>`string`

        The ID of the deleted message item.

        <strong>object</strong>`string`

        The object type. The value is fixed as `conversation.item.deleted`.
      </td>

      <td>
        ```json
        {
            "deleted": true,
            "id": "msg_xxx",
            "object": "conversation.item.deleted"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

## Use conversations in the Responses API <span id="8c6069bd19h5p" />

Use the `conversation` parameter of the Responses API to maintain context in multi-turn conversations.

> Do not pass both `previous_response_id` and `conversation` at the same time. Otherwise, the following error occurs: `[400] INVALID_REQUEST: Mutually exclusive parameters: Ensure you are only providing one of: previous_response_id or conversation.`

<CodeGroup dropdown>
  ```python Python expandable
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.getenv("DASHSCOPE_API_KEY"),
      base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
  )

  conversation = client.conversations.create(
      items=[
          {
              "type": "message",
              "role": "system",
              "content": "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess.",
          }
      ]
  )

  response1 = client.responses.create(
      conversation=conversation.id, model="qwen3.8-max", input="How old is Alice?"
  )
  print(f"First response: {response1.output_text}")

  response2 = client.responses.create(
      conversation=conversation.id, model="qwen3.8-max", input="What are her hobbies?"
  )
  print(f"Second response: {response2.output_text}")
  ```

  ```javascript Node.js expandable
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
  });

  const conversation = await client.conversations.create({
    items: [
      {
        type: "message",
        role: "system",
        content: "Alice, a gentle and resilient woman, was born in Singapore. She is 20 years old, and her hobbies are music and chess."
      }
    ]
  });

  const response1 = await client.responses.create({
    conversation: conversation.id,
    model: "qwen3.8-max",
    input: "How old is Alice?"
  });
  console.log("First response:", response1.output_text);

  const response2 = await client.responses.create({
    conversation: conversation.id,
    model: "qwen3.8-max",
    input: "What are her hobbies?"
  });
  console.log("Second response:", response2.output_text);
  ```
</CodeGroup>

## Limitations <span id="h2-limits" />

- When you create a conversation or add message items, the `items` array can contain up to 20 entries.
- The `metadata` object can contain up to 16 key-value pairs. The key can be up to 64 characters long, and the value can be up to 512 characters long.
- Conversation data is retained for a maximum of 7 days and limited to the latest 100 entries. Any data exceeding the time or quantity limit will be automatically cleared.