Skip to main content

Compatible OpenAI - Conversations

La gestion manuelle des listes de messages pour des conversations s'étendant sur plusieurs appareils ou comportant de longues interruptions peut entraîner une perte de contexte. Alibaba Cloud Model Studio fournit une API Conversations compatible avec OpenAI, utilisable conjointement avec l'API Responses pour injecter automatiquement le contexte historique. Cette fonctionnalité supprime la nécessité de synchroniser manuellement les messages et garantit la continuité des conversations dans différents scénarios et sur divers appareils.

Créer une conversation

Créez une nouvelle conversation. Vous pouvez inclure des éléments de message initiaux. Chine du Nord 2 (Pékin) : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations Singapour : POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations
Le chemin d'URL hérité /api/v2/apps/protocols/compatible-mode/v1/conversations sera bientôt obsolète. Migrez vers le nouveau chemin /compatible-mode/v1/conversations dès que possible.
Alibaba Cloud Model Studio a publié des domaines spécifiques à chaque espace de travail pour les régions Chine (Pékin) et Singapour. Les nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : de https://dashscope.aliyuncs.com vers https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de https://dashscope-intl.aliyuncs.com vers https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à votre ID d'espace de travail, disponible sur la page Workspace Details de la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.
itemsarray (Facultatif)Liste pouvant contenir jusqu'à 20 éléments de message initiaux.

Propriétés

typestring(Obligatoire)Type de message. Seul message est pris en charge.rolestring(Obligatoire)Rôle associé au message. Les instructions provenant des rôles system et developer ont une priorité supérieure à celles du rôle user. Le rôle assistant désigne les messages générés par le modèle lors d'interactions précédentes. Valeurs valides : user, assistant, system et developer.contentstring or array(Obligatoire)Contenu du message. Ce paramètre accepte des chaînes de texte brut ou des listes de contenu structuré, telles que des tableaux d'objets ResponseInputText. Le format de liste peut inclure divers types de contenu, notamment du texte.
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 (Facultatif)Métadonnées de la conversation. Utilisez ce paramètre pour stocker des informations complémentaires sous forme structurée. Spécifiez jusqu'à 16 paires clé-valeur. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.

Paramètres de réponse

created_atintegerHorodatage Unix en millisecondes indiquant la date de création de la conversation.
{
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "conversation"
}
idstringID unique de la conversation.
metadataobjectMétadonnées de la conversation. Ce paramètre stocke des informations supplémentaires sous forme de paires clé-valeur. Il peut contenir jusqu'à 16 paires. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.
objectstringType d'objet. La valeur est fixée à conversation.

Récupérer une conversation

Récupère les informations relatives à une conversation spécifiée. Chine du Nord 2 (Pékin) : GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} Singapour : GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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)

Paramètres de réponse

created_atintegerHorodatage Unix en millisecondes indiquant la date de création de la conversation.
{
    "created_at": 1771316949128,
    "id": "conv_xxx",
    "metadata": {
        "topic": "demo"
    },
    "object": "conversation"
}
idstringID unique de la conversation.
metadataobjectMétadonnées de la conversation. Ce paramètre stocke des informations supplémentaires sous forme de paires clé-valeur. Il peut contenir jusqu'à 16 paires. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.
objectstringType d'objet. La valeur est fixée à conversation.

Mettre à jour une conversation

Met à jour les métadonnées d'une conversation. Chine du Nord 2 (Pékin) : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} Singapour : POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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(Obligatoire)Métadonnées de la conversation. Ce paramètre remplace intégralement les métadonnées existantes. Spécifiez jusqu'à 16 paires clé-valeur. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.

Paramètres de réponse

created_atintegerHorodatage Unix en millisecondes indiquant la date de création de la conversation.
{
    "created_at": 1771318152759,
    "id": "conv_xxx",
    "metadata": {
        "topic": "update"
    },
    "object": "conversation"
}
idstringID unique de la conversation.
metadataobjectMétadonnées de la conversation. Ce paramètre stocke des informations supplémentaires sous forme de paires clé-valeur. Il peut contenir jusqu'à 16 paires. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.
objectstringType d'objet. La valeur est fixée à conversation.

Supprimer une conversation

Supprime une conversation spécifiée. Les éléments de message qu'elle contient ne sont pas supprimés. Chine du Nord 2 (Pékin) : DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id} Singapour : DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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)

Paramètres de réponse

deletedbooleanIndique si la suppression a réussi.
{
    "deleted": true,
    "id": "conv_xxx",
    "object": "conversation.deleted"
}
idstringID de la conversation supprimée.
objectstringType d'objet. La valeur est fixée à conversation.deleted.

Créer des éléments

Ajoute des éléments de message à une conversation spécifiée. Chine du Nord 2 (Pékin) : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items Singapour : POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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(Obligatoire)Liste d'éléments de message. Vous pouvez ajouter jusqu'à 20 éléments à la fois.

Propriétés

typestring(Obligatoire)Type de message. Seul message est pris en charge.rolestring(Obligatoire)Rôle associé au message. Les instructions provenant des rôles system et developer ont une priorité supérieure à celles du rôle user. Le rôle assistant désigne les messages générés par le modèle lors d'interactions précédentes. Valeurs valides : user, assistant, system et developer.contentstring or array(Obligatoire)Contenu du message. Ce paramètre accepte des chaînes de texte brut ou des listes de contenu structuré, telles que des tableaux d'objets ResponseInputText. Le format de liste peut inclure divers types de contenu, notamment du texte.

Paramètres de réponse

dataarray[object]Liste des éléments de message créés.

Propriétés

idstringID unique de l'élément de message.contentstring or arrayContenu du message. Il peut s'agir d'une chaîne de texte brut ou d'une liste de contenu structuré, telle qu'un tableau d'objets ResponseInputText.rolestringRôle du message. Valeurs valides : user, assistant, system et developer.statusstringÉtat de traitement du message. Valeurs valides : in_progress, completed et incomplete.typestringType de l'élément de message. La valeur est fixée à 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 du premier élément de message de la liste.
has_morebooleanIndique si des données supplémentaires sont disponibles.
last_idstringID du dernier élément de message de la liste.

Lister les éléments

Liste tous les éléments de message d'une conversation. Chine du Nord 2 (Pékin) : GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items Singapour : GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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 (Facultatif)Curseur de pagination. Ne retourne que les éléments de message créés après l'ID de message spécifié.
orderstring (Facultatif)Ordre de tri. Valeurs valides : asc pour un ordre croissant et desc pour un ordre décroissant. La valeur par défaut est desc.
limitinteger (Facultatif)Nombre d'éléments à retourner. La valeur doit être un entier compris entre 1 et 100. La valeur par défaut est 20.

Paramètres de réponse

dataarray[object]Liste des éléments de message.

Propriétés

idstringID unique de l'élément de message.contentstring or arrayContenu du message. Il peut s'agir d'une chaîne de texte brut ou d'une liste de contenu structuré, telle qu'un tableau d'objets ResponseInputText.rolestringRôle du message. Valeurs valides : user, assistant, system et developer.statusstringÉtat de traitement du message. Valeurs valides : in_progress, completed et incomplete.typestringType de l'élément de message. La valeur est fixée à 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 du premier élément de message de la liste.
has_morebooleanIndique si des données supplémentaires sont disponibles.
last_idstringID du dernier élément de message de la liste.
objectstringType d'objet. La valeur est fixée à list.

Récupérer un élément

Récupère les détails d'un élément de message spécifié. Chine du Nord 2 (Pékin) : GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id} Singapour : GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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(Obligatoire, Chemin)ID de l'élément de message.

Paramètres de réponse

contentarray[object]Liste du contenu du message contenant un ou plusieurs objets de contenu.

Propriétés

typestringType de contenu, par exemple input_text pour le texte saisi par l'utilisateur ou output_text pour le texte généré par le modèle.textstringContenu textuel.
{
    "content": [
        {
            "text": "Alice's major is teacher education",
            "type": "input_text"
        }
    ],
    "id": "msg_xxx",
    "role": "user",
    "status": "completed",
    "type": "message"
}
idstringID unique de l'élément de message.
rolestringRôle du message. Valeurs valides : user, assistant, system et developer.
statusstringÉtat de traitement du message. Valeurs valides : in_progress, completed et incomplete.
typestringType de l'élément de message. La valeur est fixée à message.

Supprimer un élément

Supprime un élément de message spécifié. Chine du Nord 2 (Pékin) : DELETE https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id} Singapour : DELETE https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/conversations/{conversation_id}/items/{item_id}
conversation_idstring(Obligatoire, Chemin)ID de la conversation.
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(Obligatoire, Chemin)ID de l'élément de message.

Paramètres de réponse

deletedbooleanIndique si l'élément a été supprimé avec succès.
{
    "deleted": true,
    "id": "msg_xxx",
    "object": "conversation.item.deleted"
}
idstringID de l'élément de message supprimé.
objectstringType d'objet. La valeur est fixée à conversation.item.deleted.

Utiliser les conversations dans l'API Responses

Utilisez le paramètre conversation de l'API Responses pour maintenir le contexte dans les conversations multi-tours.
Ne transmettez pas simultanément previous_response_id et conversation. Dans le cas contraire, l'erreur suivante se produit : [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}")

Limites

  • Lors de la création d'une conversation ou de l'ajout d'éléments de message, le tableau items peut contenir jusqu'à 20 entrées.
  • L'objet metadata peut contenir jusqu'à 16 paires clé-valeur. La clé peut comporter jusqu'à 64 caractères et la valeur jusqu'à 512 caractères.
  • Les données de conversation sont conservées pendant 7 jours maximum et limitées aux 100 entrées les plus récentes. Toute donnée dépassant la limite de temps ou de quantité est automatiquement effacée.