Manajemen sesi API Percakapan - Alibaba Cloud Model Studio

Mengelola daftar pesan secara manual untuk percakapan yang berlangsung di beberapa perangkat atau mengalami jeda panjang dapat menyebabkan hilangnya konteks. Alibaba Cloud Model Studio menyediakan API Percakapan yang kompatibel dengan OpenAI yang dapat digunakan bersama API Responses untuk secara otomatis menyisipkan konteks historis, sehingga menghilangkan kebutuhan akan sinkronisasi pesan manual dan memastikan kelangsungan percakapan di berbagai skenario dan perangkat.

Buat percakapan

Membuat percakapan baru. Anda dapat secara opsional menyertakan item pesan awal.

North China 2 (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

PentingJalur URL lama /api/v2/apps/protocols/compatible-mode/v1/conversations segera tidak akan didukung lagi. Segera migrasikan ke jalur baru /compatible-mode/v1/conversations.

PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru berikut:

China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan pada halaman Workspace Details di Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi penuh.

itemsarray (Opsional)

Daftar hingga 20 item pesan awal.

Properties

typestring(Wajib)

Tipe pesan. Hanya message yang didukung.

rolestring(Wajib)

Peran pesan. Instruksi dari peran system dan developer memiliki prioritas lebih tinggi dibandingkan instruksi dari peran user. Peran assistant menunjukkan pesan yang dihasilkan oleh model dalam interaksi sebelumnya. Nilai yang valid adalah user, assistant, system, dan developer.

contentstring or array(Wajib)

Konten pesan. Parameter ini mendukung string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText. Format daftar dapat mencakup berbagai tipe konten, seperti teks.

metadataobject (Opsional)

Metadata percakapan. Gunakan parameter ini untuk menyimpan informasi tambahan tentang percakapan dalam format terstruktur. Tentukan hingga 16 pasangan kunci-nilai. Panjang kunci maksimal 64 karakter, dan panjang nilai maksimal 512 karakter.

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

Parameter respons

created_atinteger

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

idstring

ID unik percakapan.

metadataobject

Metadata percakapan. Parameter ini menyimpan informasi tambahan sebagai pasangan kunci-nilai. Dapat berisi hingga 16 pasangan. Panjang kunci maksimal 64 karakter, dan panjang nilai maksimal 512 karakter.

objectstring

Tipe objek. Nilainya tetap conversation.

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

Ambil percakapan

Mengambil informasi untuk percakapan tertentu.

North China 2 (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(Wajib, Path)

ID percakapan.

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'

Parameter respons

created_atinteger

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

idstring

ID unik percakapan.

metadataobject

objectstring

Tipe objek. Nilainya tetap conversation.

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

Perbarui percakapan

Memperbarui metadata percakapan.

North China 2 (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(Wajib, Path)

ID percakapan.

metadataobject(Wajib)

Metadata percakapan. Parameter ini sepenuhnya menimpa metadata yang ada. Tentukan hingga 16 pasangan kunci-nilai. Panjang kunci maksimal 64 karakter, dan panjang nilai maksimal 512 karakter.

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

Parameter respons

created_atinteger

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

idstring

ID unik percakapan.

metadataobject

objectstring

Tipe objek. Nilainya tetap conversation.

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

Hapus percakapan

Menghapus percakapan tertentu. Item pesan di dalam percakapan tidak dihapus.

North China 2 (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(Wajib, Path)

ID percakapan.

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'

Parameter respons

deletedboolean

Menunjukkan apakah penghapusan berhasil.

idstring

ID percakapan yang dihapus.

objectstring

Tipe objek. Nilainya tetap conversation.deleted.

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

Buat item

Menambahkan item pesan ke percakapan tertentu.

North China 2 (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(Wajib, Path)

ID percakapan.

itemsarray(Wajib)

Daftar item pesan. Anda dapat menambahkan hingga 20 item sekaligus.

Properties

typestring(Wajib)

Tipe pesan. Hanya message yang didukung.

rolestring(Wajib)

contentstring or array(Wajib)

Konten pesan. Parameter ini mendukung string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText. Format daftar dapat mencakup berbagai tipe konten, seperti teks.

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

Parameter respons

dataarray[object]

Daftar item pesan yang dibuat.

Properties

idstring

ID unik item pesan.

contentstring or array

Konten pesan. Ini dapat berupa string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText.

rolestring

Peran pesan. Nilai yang valid adalah user, assistant, system, dan developer.

statusstring

Status pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.

typestring

Tipe item pesan. Nilainya tetap message.

first_idstring

ID item pesan pertama dalam daftar.

has_moreboolean

Menunjukkan apakah masih ada data lain yang tersedia.

last_idstring

ID item pesan terakhir dalam daftar.

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

Daftar item

Menampilkan semua item pesan dalam percakapan.

North China 2 (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(Wajib, Path)

ID percakapan.

afterstring (Opsional)

Kursor pagination. Hanya mengembalikan item pesan yang dibuat setelah ID pesan tertentu.

orderstring (Opsional)

Urutan pengurutan. Nilai yang valid adalah asc untuk ascending dan desc untuk descending. Nilai default adalah desc.

limitinteger (Opsional)

Jumlah item yang dikembalikan. Nilainya harus bilangan bulat antara 1 hingga 100. Nilai default adalah 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'

Parameter respons

dataarray[object]

Daftar item pesan.

Properties

idstring

ID unik item pesan.

contentstring or array

Konten pesan. Ini dapat berupa string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText.

rolestring

Peran pesan. Nilai yang valid adalah user, assistant, system, dan developer.

statusstring

Status pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.

typestring

Tipe item pesan. Nilainya tetap message.

first_idstring

ID item pesan pertama dalam daftar.

has_moreboolean

Menunjukkan apakah masih ada data lain yang tersedia.

last_idstring

ID item pesan terakhir dalam daftar.

objectstring

Tipe objek. Nilainya tetap 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"
}

Ambil item

Mengambil detail untuk item pesan tertentu.

North China 2 (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(Wajib, Path)

ID percakapan.

item_idstring(Wajib, Path)

ID item pesan.

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'

Parameter respons

contentarray[object]

Daftar konten pesan yang berisi satu atau lebih objek konten.

Properties

typestring

Tipe konten, seperti input_text untuk teks input pengguna atau output_text untuk teks output model.

textstring

Konten teks.

idstring

ID unik item pesan.

rolestring

Peran pesan. Nilai yang valid adalah user, assistant, system, dan developer.

statusstring

Status pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.

typestring

Tipe item pesan. Nilainya tetap message.

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

Hapus item

Menghapus item pesan tertentu.

North China 2 (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(Wajib, Path)

ID percakapan.

item_idstring(Wajib, Path)

ID item pesan.

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'

Parameter respons

deletedboolean

Menunjukkan apakah item berhasil dihapus.

idstring

ID item pesan yang dihapus.

objectstring

Tipe objek. Nilainya tetap conversation.item.deleted.

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

Gunakan percakapan dalam API Responses

Gunakan parameter conversation dari API Responses untuk mempertahankan konteks dalam percakapan multi-putaran.

Jangan meneruskan kedua parameter previous_response_id dan conversation secara bersamaan. Jika dilakukan, error berikut akan muncul: [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);

Batasan

Saat membuat percakapan atau menambahkan item pesan, array items dapat berisi hingga 20 entri.
Objek metadata dapat berisi hingga 16 pasangan kunci-nilai. Panjang kunci maksimal 64 karakter, dan panjang nilai maksimal 512 karakter.
Data percakapan disimpan maksimal selama 7 hari dan dibatasi hingga 100 entri terbaru. Data apa pun yang melebihi batas waktu atau jumlah tersebut akan dihapus secara otomatis.