Gerenciamento de sessão da API Conversations - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Gerenciar manualmente listas de mensagens em conversas que abrangem vários dispositivos ou apresentam longas interrupções pode causar perda de contexto. O Alibaba Cloud Model Studio oferece uma API Conversations compatível com OpenAI que, usada com a Responses API, injeta automaticamente o histórico de contexto. Isso elimina a necessidade de sincronizar mensagens manualmente e garante a continuidade da conversa em diferentes cenários e dispositivos.

Criar conversa

Crie uma nova conversa. Opcionalmente, inclua itens de mensagem iniciais.

China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations

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

ImportanteO caminho de URL legado /api/v2/apps/protocols/compatible-mode/v1/conversations será descontinuado em breve. Migre para o novo caminho /compatible-mode/v1/conversations o mais rápido possível.

ImportanteO Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:

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

{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

itemsarray (Opcional)

Lista de até 20 itens de mensagem iniciais.

Propriedades

typestring(Obrigatório)

Tipo da mensagem. Apenas message é suportado.

rolestring(Obrigatório)

Função da mensagem. Instruções das funções system e developer têm prioridade sobre as da função user. A função assistant indica mensagens geradas pelo modelo em interações anteriores. Valores válidos: user, assistant, system e developer.

contentstring ou array(Obrigatório)

Conteúdo da mensagem. Este parâmetro aceita strings de texto simples ou listas de conteúdo estruturado, como arrays de objetos ResponseInputText. O formato de lista pode incluir vários tipos de conteúdo, como texto.

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)

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

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."
            }
        ]
    }'

metadataobject (Opcional)

Metadados da conversa. Use este parâmetro para armazenar informações adicionais da conversa em formato estruturado. Especifique até 16 pares chave-valor. A chave pode ter até 64 caracteres e o valor até 512 caracteres.

Parâmetros de resposta

created_atinteger

Timestamp Unix em milissegundos indicando quando a conversa foi criada.

{
        "created_at": 1771316949128,
        "id": "conv_xxx",
        "metadata": {
            "topic": "demo"
        },
        "object": "conversation"
    }

idstring

ID exclusivo da conversa.

metadataobject

Metadados da conversa. Este parâmetro armazena informações adicionais como pares chave-valor. Pode conter até 16 pares. A chave pode ter até 64 caracteres e o valor até 512 caracteres.

objectstring

Tipo do objeto. Valor fixo: conversation.

Recuperar conversa

Recupera informações de uma conversa especificada.

China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

cURL

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
    --header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Parâmetros de resposta

created_atinteger

Timestamp Unix em milissegundos indicando quando a conversa foi criada.

{
        "created_at": 1771316949128,
        "id": "conv_xxx",
        "metadata": {
            "topic": "demo"
        },
        "object": "conversation"
    }

idstring

ID exclusivo da conversa.

metadataobject

Metadados da conversa. Este parâmetro armazena informações adicionais como pares chave-valor. Pode conter até 16 pares. A chave pode ter até 64 caracteres e o valor até 512 caracteres.

objectstring

Tipo do objeto. Valor fixo: conversation.

Atualizar conversa

Atualize os metadados de uma conversa.

China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

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

metadataobject(Obrigatório)

Metadados da conversa. Este parâmetro substitui completamente os metadados existentes. Especifique até 16 pares chave-valor. A chave pode ter até 64 caracteres e o valor até 512 caracteres.

Parâmetros de resposta

created_atinteger

Timestamp Unix em milissegundos indicando quando a conversa foi criada.

{
        "created_at": 1771318152759,
        "id": "conv_xxx",
        "metadata": {
            "topic": "update"
        },
        "object": "conversation"
    }

idstring

ID exclusivo da conversa.

metadataobject

Metadados da conversa. Este parâmetro armazena informações adicionais como pares chave-valor. Pode conter até 16 pares. A chave pode ter até 64 caracteres e o valor até 512 caracteres.

objectstring

Tipo do objeto. Valor fixo: conversation.

Excluir conversa

Exclua uma conversa especificada. Os itens de mensagem da conversa não são excluídos.

China (Beijing): DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

cURL

curl --location --request DELETE 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/conv_xxx' \
    --header 'Authorization: Bearer $DASHSCOPE_API_KEY'

Parâmetros de resposta

deletedboolean

Indica se a exclusão foi bem-sucedida.

{
        "deleted": true,
        "id": "conv_xxx",
        "object": "conversation.deleted"
    }

idstring

ID da conversa excluída.

objectstring

Tipo do objeto. Valor fixo: conversation.deleted.

Criar itens

Adiciona itens de mensagem a uma conversa especificada.

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

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

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"
                }]
            }
        ]
    }'

itemsarray(Obrigatório)

Lista de itens de mensagem. É possível adicionar até 20 itens por vez.

Propriedades

typestring(Obrigatório)

Tipo da mensagem. Apenas message é suportado.

rolestring(Obrigatório)

contentstring ou array(Obrigatório)

Parâmetros de resposta

dataarray[object]

Lista dos itens de mensagem criados.

Propriedades

idstring

ID exclusivo do item de mensagem.

contentstring ou array

Conteúdo da mensagem. Pode ser uma string de texto simples ou uma lista de conteúdo estruturado, como um array de objetos ResponseInputText.

rolestring

Função da mensagem. Valores válidos: user, assistant, system e developer.

statusstring

Status de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.

typestring

Tipo do item de mensagem. Valor fixo: message.

{
        "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"
    }

first_idstring

ID do primeiro item de mensagem na lista.

has_moreboolean

Indica se há mais dados disponíveis.

last_idstring

ID do último item de mensagem na lista.

Listar itens

Lista todos os itens de mensagem de uma conversa.

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

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

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'

afterstring (Opcional)

Cursor de paginação. Retorna apenas itens de mensagem criados após o ID de mensagem especificado.

orderstring (Opcional)

Ordem de classificação. Valores válidos: asc para ascendente e desc para descendente. Valor padrão: desc.

limitinteger (Opcional)

Número de itens a retornar. O valor deve ser um inteiro entre 1 e 100. Valor padrão: 20.

Parâmetros de resposta

dataarray[object]

Lista dos itens de mensagem.

Propriedades

idstring

ID exclusivo do item de mensagem.

contentstring ou array

Conteúdo da mensagem. Pode ser uma string de texto simples ou uma lista de conteúdo estruturado, como um array de objetos ResponseInputText.

rolestring

Função da mensagem. Valores válidos: user, assistant, system e developer.

statusstring

Status de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.

typestring

Tipo do item de mensagem. Valor fixo: message.

{
        "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"
    }

first_idstring

ID do primeiro item de mensagem na lista.

has_moreboolean

Indica se há mais dados disponíveis.

last_idstring

ID do último item de mensagem na lista.

objectstring

Tipo do objeto. Valor fixo: list.

Recuperar item

Recupera os detalhes de um item de mensagem especificado.

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

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

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'

item_idstring(Obrigatório, Path)

ID do item de mensagem.

Parâmetros de resposta

contentarray[object]

Lista de conteúdo da mensagem contendo um ou mais objetos de conteúdo.

Propriedades

typestring

Tipo de conteúdo, como input_text para texto de entrada do usuário ou output_text para texto de saída do modelo.

textstring

Conteúdo de texto.

{
        "content": [
            {
                "text": "Alice's major is teacher education",
                "type": "input_text"
            }
        ],
        "id": "msg_xxx",
        "role": "user",
        "status": "completed",
        "type": "message"
    }

idstring

ID exclusivo do item de mensagem.

rolestring

Função da mensagem. Valores válidos: user, assistant, system e developer.

statusstring

Status de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.

typestring

Tipo do item de mensagem. Valor fixo: message.

Excluir item

Exclua um item de mensagem especificado.

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

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

conversation_idstring(Obrigatório, Path)

ID da conversa.

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)

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

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'

item_idstring(Obrigatório, Path)

ID do item de mensagem.

Parâmetros de resposta

deletedboolean

Indica se o item foi excluído com sucesso.

{
        "deleted": true,
        "id": "msg_xxx",
        "object": "conversation.item.deleted"
    }

idstring

ID do item de mensagem excluído.

objectstring

Tipo do objeto. Valor fixo: conversation.item.deleted.

Usar conversas na Responses API

Use o parâmetro conversation da Responses API para manter o contexto em conversas de múltiplas rodadas.

Não passe simultaneamente previous_response_id e conversation. Caso contrário, ocorrerá o seguinte erro: [400] INVALID_REQUEST: Mutually exclusive parameters: Ensure you are only providing one of: previous_response_id or conversation.

Python

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.7-plus", input="How old is Alice?"
)
print(f"First response: {response1.output_text}")

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

Node.js

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.7-plus",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.7-plus",
  input: "What are her hobbies?"
});
console.log("Second response:", response2.output_text);

Limitações

Ao criar uma conversa ou adicionar itens de mensagem, o array items pode conter até 20 entradas.
O objeto metadata pode conter até 16 pares chave-valor. A chave pode ter até 64 caracteres e o valor até 512 caracteres.
Os dados da conversa são retidos por no máximo 7 dias, limitados às 100 entradas mais recentes. Dados que excedam o limite de tempo ou quantidade serão removidos automaticamente.