Skip to main content

Compatible con OpenAI - Conversaciones

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
La 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.
Alibaba 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)

Parámetros de respuesta

created_atintegerLa marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.idstringEl ID único de la conversación.metadataobjectLos 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.objectstringEl 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)

Parámetros de respuesta

created_atintegerLa marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.idstringEl ID único de la conversación.metadataobjectLos 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.objectstringEl 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)

Parámetros de respuesta

created_atintegerLa marca de tiempo Unix en milisegundos que indica cuándo se creó la conversación.idstringEl ID único de la conversación.metadataobjectLos 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.objectstringEl 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)

Parámetros de respuesta

deletedbooleanIndica si la eliminación fue exitosa.idstringEl ID de la conversación eliminada.objectstringEl 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)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.
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)

Parámetros de respuesta

dataarray[object]Una lista de los elementos de mensaje creados.

Propiedades

idstringEl ID único del elemento de mensaje.contentstring or arrayEl contenido del mensaje. Puede ser una cadena de texto sin formato o una lista de contenido estructurado, como una matriz de objetos ResponseInputText.rolestringEl rol del mensaje. Los valores válidos son user, assistant, system y developer.statusstringEl estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.typestringEl tipo del elemento de mensaje. El valor está fijado como message.
first_idstringEl ID del primer elemento de mensaje en la lista.has_morebooleanIndica si hay más datos disponibles.last_idstringEl 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)

Parámetros de respuesta

dataarray[object]Una lista de los elementos de mensaje.

Propiedades

idstringEl ID único del elemento de mensaje.contentstring or arrayEl contenido del mensaje. Puede ser una cadena de texto sin formato o una lista de contenido estructurado, como una matriz de objetos ResponseInputText.rolestringEl rol del mensaje. Los valores válidos son user, assistant, system y developer.statusstringEl estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.typestringEl tipo del elemento de mensaje. El valor está fijado como message.
first_idstringEl ID del primer elemento de mensaje en la lista.has_morebooleanIndica si hay más datos disponibles.last_idstringEl ID del último elemento de mensaje en la lista.objectstringEl 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)

Parámetros de respuesta

contentarray[object]Una lista de contenido de mensajes que contiene uno o más objetos de contenido.

Propiedades

typestringEl tipo de contenido, como input_text para texto de entrada del usuario o output_text para texto de salida del modelo.textstringEl contenido de texto.
idstringEl ID único del elemento de mensaje.rolestringEl rol del mensaje. Los valores válidos son user, assistant, system y developer.statusstringEl estado de procesamiento del mensaje. Los valores válidos son in_progress, completed y incomplete.typestringEl 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)

Parámetros de respuesta

deletedbooleanIndica si el elemento se eliminó correctamente.idstringEl ID del elemento de mensaje eliminado.objectstringEl 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}")

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.