Gestión de sesiones de la API de Conversaciones - Alibaba Cloud Model Studio

Gestionar manualmente listas de mensajes para conversaciones que abarcan múltiples dispositivos o tienen interrupciones prolongadas puede provocar la pérdida de contexto. Alibaba Cloud Model Studio proporciona una API de Conversaciones compatible con OpenAI que puede utilizar junto con la API de Respuestas para inyectar automáticamente el contexto histórico. Esto elimina la necesidad de sincronizar mensajes manualmente y garantiza la continuidad de la conversación en diferentes escenarios y dispositivos.

Crear conversación

Crea una nueva conversación. Opcionalmente, puede incluir elementos de mensaje iniciales.

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

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

ImportanteLa ruta de URL heredada /api/v2/apps/protocols/compatible-mode/v1/conversations quedará obsoleta próximamente. Migre a la nueva ruta /compatible-mode/v1/conversations lo antes posible.

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.

itemsarray (Opcional)

Una lista de hasta 20 elementos de mensaje iniciales.

Propiedades

typestring(Obligatorio)

El tipo de mensaje. Solo se admite message.

rolestring(Obligatorio)

El rol del mensaje. Las instrucciones de los roles system y developer tienen mayor prioridad que las instrucciones del rol user. El rol assistant indica mensajes que fueron generados por el modelo en interacciones anteriores. Los valores válidos son user, assistant, system y developer.

contentstring or array(Obligatorio)

El contenido del mensaje. Este parámetro admite cadenas de texto sin formato o listas de contenido estructurado, como matrices de objetos ResponseInputText. El formato de lista puede incluir varios tipos de contenido, como texto.

metadataobject (Opcional)

Los metadatos de la conversación. Utilice este parámetro para almacenar información adicional de la conversación en un formato estructurado. Especifique hasta 16 pares clave-valor. La clave puede tener una longitud máxima de 64 caracteres y el valor puede tener una longitud máxima de 512 caracteres.

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

Parámetros de respuesta

created_atinteger

La marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.

idstring

El ID único de la conversación.

metadataobject

Los metadatos de la conversación. Este parámetro almacena información adicional como pares clave-valor. Puede contener hasta 16 pares. La clave puede tener una longitud máxima de 64 caracteres y el valor puede tener una longitud máxima de 512 caracteres.

objectstring

El tipo de objeto. El valor está fijado como conversation.

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

Recuperar conversación

Recupera información de una conversación especificada.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

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 respuesta

created_atinteger

La marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.

idstring

El ID único de la conversación.

metadataobject

objectstring

El tipo de objeto. El valor está fijado como conversation.

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

Actualizar conversación

Actualiza los metadatos de una conversación.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

metadataobject(Requerido)

Los metadatos de la conversación. Este parámetro sobrescribe por completo los metadatos existentes. Especifique hasta 16 pares clave-valor. La clave puede tener una longitud máxima de 64 caracteres y el valor puede tener una longitud máxima de 512 caracteres.

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

Parámetros de respuesta

created_atinteger

La marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.

idstring

El ID único de la conversación.

metadataobject

objectstring

El tipo de objeto. El valor está fijado como conversation.

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

Eliminar conversación

Elimina una conversación especificada. Los elementos de mensaje dentro de la conversación no se eliminan.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

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 respuesta

deletedboolean

Indica si la eliminación fue exitosa.

idstring

El ID de la conversación eliminada.

objectstring

El tipo de objeto. El valor está fijado como conversation.deleted.

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

Crear elementos

Añade elementos de mensaje a una conversación especificada.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

itemsarray(Requerido)

Una lista de elementos de mensaje. Puede añadir hasta 20 elementos a la vez.

Propiedades

typestring(Obligatorio)

El tipo de mensaje. Solo se admite message.

rolestring(Obligatorio)

contentstring or array(Obligatorio)

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

Parámetros de respuesta

dataarray[object]

Una lista de los elementos de mensaje creados.

Propiedades

idstring

El ID único del elemento de mensaje.

contentstring or array

El contenido del mensaje. Puede ser una cadena de texto sin formato o una lista de contenido estructurado, como una matriz de objetos ResponseInputText.

rolestring

El rol del mensaje. Los valores válidos son user, assistant, system y developer.

statusstring

El estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.

typestring

El tipo del elemento de mensaje. El valor está fijado como message.

first_idstring

El ID del primer elemento de mensaje en la lista.

has_moreboolean

Indica si hay más datos disponibles.

last_idstring

El ID del último elemento de mensaje en la lista.

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

Listar elementos

Enumera todos los elementos de mensaje en una conversación.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

afterstring (Opcional)

El cursor de paginación. Devuelve solo los elementos de mensaje creados después del ID de mensaje especificado.

orderstring (Opcional)

El orden de clasificación. Los valores válidos son asc para ascendente y desc para descendente. El valor predeterminado es desc.

limitinteger (Opcional)

El número de elementos a devolver. El valor debe ser un entero de 1 a 100. El valor predeterminado es 20.

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'

Parámetros de respuesta

dataarray[object]

Una lista de los elementos de mensaje.

Propiedades

idstring

El ID único del elemento de mensaje.

contentstring or array

El contenido del mensaje. Puede ser una cadena de texto sin formato o una lista de contenido estructurado, como una matriz de objetos ResponseInputText.

rolestring

El rol del mensaje. Los valores válidos son user, assistant, system y developer.

statusstring

El estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.

typestring

El tipo del elemento de mensaje. El valor está fijado como message.

first_idstring

El ID del primer elemento de mensaje en la lista.

has_moreboolean

Indica si hay más datos disponibles.

last_idstring

El ID del último elemento de mensaje en la lista.

objectstring

El tipo de objeto. El valor está fijado como list.

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

Recuperar elemento

Recupera los detalles de un elemento de mensaje especificado.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

item_idstring(Requerido, Ruta)

El ID del elemento de mensaje.

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'

Parámetros de respuesta

contentarray[object]

Una lista de contenido de mensajes que contiene uno o más objetos de contenido.

Propiedades

typestring

El tipo de contenido, como input_text para texto de entrada del usuario o output_text para texto de salida del modelo.

textstring

El contenido de texto.

idstring

El ID único del elemento de mensaje.

rolestring

El rol del mensaje. Los valores válidos son user, assistant, system y developer.

statusstring

El estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.

typestring

El tipo del elemento de mensaje. El valor está fijado como message.

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

Eliminar elemento

Elimina un elemento de mensaje especificado.

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

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

conversation_idstring(Requerido, Ruta)

El ID de la conversación.

item_idstring(Requerido, Ruta)

El ID del elemento de mensaje.

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'

Parámetros de respuesta

deletedboolean

Indica si el elemento se eliminó correctamente.

idstring

El ID del elemento de mensaje eliminado.

objectstring

El tipo de objeto. El valor está fijado como conversation.item.deleted.

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

Usar conversaciones en la API de Responses

Use el parámetro conversation de la API de Responses para mantener el contexto en conversaciones de múltiples turnos.

No pase previous_response_id y conversation al mismo tiempo. De lo contrario, se producirá el siguiente error: [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.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}")

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

Limitaciones

Cuando crea una conversación o añade elementos de mensaje, la matriz items puede contener hasta 20 entradas.
El objeto metadata puede contener hasta 16 pares clave-valor. La clave puede tener una longitud máxima de 64 caracteres y el valor puede tener una longitud máxima de 512 caracteres.
Los datos de la conversación se conservan durante un máximo de 7 días y están limitados a las últimas 100 entradas. Cualquier dato que exceda el límite de tiempo o cantidad se eliminará automáticamente.