Skip to main content
Toolkit/Framework

Compatível com OpenAI - Conversas

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
O 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.
O 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)
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_atintegerTimestamp Unix em milissegundos indicando quando a conversa foi criada.
{
        "created_at": 1771316949128,
        "id": "conv_xxx",
        "metadata": {
            "topic": "demo"
        },
        "object": "conversation"
    }
idstringID exclusivo da conversa.
metadataobjectMetadados 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.
objectstringTipo 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)

Parâmetros de resposta

created_atintegerTimestamp Unix em milissegundos indicando quando a conversa foi criada.
{
        "created_at": 1771316949128,
        "id": "conv_xxx",
        "metadata": {
            "topic": "demo"
        },
        "object": "conversation"
    }
idstringID exclusivo da conversa.
metadataobjectMetadados 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.
objectstringTipo 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)
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_atintegerTimestamp Unix em milissegundos indicando quando a conversa foi criada.
{
        "created_at": 1771318152759,
        "id": "conv_xxx",
        "metadata": {
            "topic": "update"
        },
        "object": "conversation"
    }
idstringID exclusivo da conversa.
metadataobjectMetadados 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.
objectstringTipo 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)

Parâmetros de resposta

deletedbooleanIndica se a exclusão foi bem-sucedida.
{
        "deleted": true,
        "id": "conv_xxx",
        "object": "conversation.deleted"
    }
idstringID da conversa excluída.
objectstringTipo 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)
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)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.

Parâmetros de resposta

dataarray[object]Lista dos itens de mensagem criados.

Propriedades

idstringID exclusivo do item de mensagem.contentstring ou arrayConteúdo da mensagem. Pode ser uma string de texto simples ou uma lista de conteúdo estruturado, como um array de objetos ResponseInputText.rolestringFunção da mensagem. Valores válidos: user, assistant, system e developer.statusstringStatus de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.typestringTipo 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_idstringID do primeiro item de mensagem na lista.
has_morebooleanIndica se há mais dados disponíveis.
last_idstringID 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)
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

idstringID exclusivo do item de mensagem.contentstring ou arrayConteúdo da mensagem. Pode ser uma string de texto simples ou uma lista de conteúdo estruturado, como um array de objetos ResponseInputText.rolestringFunção da mensagem. Valores válidos: user, assistant, system e developer.statusstringStatus de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.typestringTipo 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_idstringID do primeiro item de mensagem na lista.
has_morebooleanIndica se há mais dados disponíveis.
last_idstringID do último item de mensagem na lista.
objectstringTipo 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)
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

typestringTipo de conteúdo, como input_text para texto de entrada do usuário ou output_text para texto de saída do modelo.textstringConteúdo de texto.
{
        "content": [
            {
                "text": "Alice's major is teacher education",
                "type": "input_text"
            }
        ],
        "id": "msg_xxx",
        "role": "user",
        "status": "completed",
        "type": "message"
    }
idstringID exclusivo do item de mensagem.
rolestringFunção da mensagem. Valores válidos: user, assistant, system e developer.
statusstringStatus de processamento da mensagem. Valores válidos: in_progress, completed e incomplete.
typestringTipo 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)
item_idstring(Obrigatório, Path)ID do item de mensagem.

Parâmetros de resposta

deletedbooleanIndica se o item foi excluído com sucesso.
{
        "deleted": true,
        "id": "msg_xxx",
        "object": "conversation.item.deleted"
    }
idstringID do item de mensagem excluído.
objectstringTipo 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}")

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.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais