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 Conversations yang kompatibel dengan OpenAI, yang dapat digunakan bersama API Responses untuk secara otomatis menyisipkan konteks historis. Pendekatan ini menghilangkan kebutuhan akan sinkronisasi pesan manual dan memastikan kelangsungan percakapan di berbagai skenario serta 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

Penting

Jalur URL lama /api/v2/apps/protocols/compatible-mode/v1/responses akan segera ditinggalkan. Segera migrasikan ke jalur baru /compatible-mode/v1/responses.

Penting

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 menyarankan Anda bermigrasi ke domain baru berikut:

China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: 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 Detail Ruang Kerja di Konsol Model Studio. Domain lama tetap berfungsi sepenuhnya.

items array (Opsional)

Daftar hingga 20 item pesan awal.

Properti

type string (Wajib)

Tipe pesan. Hanya message yang didukung.

role string (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.

content string atau 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",
)

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

metadata object (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.

Parameter respons

created_at integer

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

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

id string

ID unik percakapan.

metadata object

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.

object string

Tipe objek. Nilainya tetap 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_id string (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_at integer

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

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

id string

ID unik percakapan.

metadata object

object string

Tipe objek. Nilainya tetap 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_id string (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",
)

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

metadata object (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.

Parameter respons

created_at integer

Timestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.

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

id string

ID unik percakapan.

metadata object

object string

Tipe objek. Nilainya tetap 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_id string (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

deleted boolean

Menunjukkan apakah penghapusan berhasil.

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

id string

ID percakapan yang dihapus.

object string

Tipe objek. Nilainya tetap 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_id string (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",
)

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

items array (Wajib)

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

Properti

type string (Wajib)

Tipe pesan. Hanya message yang didukung.

role string (Wajib)

content string atau 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.

Parameter respons

data array[object]

Daftar item pesan yang dibuat.

Properti

id string

ID unik item pesan.

content string atau array

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

role string

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

status string

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

type string

Tipe item pesan. Nilainya tetap 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_id string

ID item pesan pertama dalam daftar.

has_more boolean

Menunjukkan apakah masih ada data tambahan.

last_id string

ID item pesan terakhir dalam daftar.

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_id string (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",
)

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'

after string (Opsional)

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

order string (Opsional)

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

limit integer (Opsional)

Jumlah item yang dikembalikan. Nilainya harus bilangan bulat antara 1 hingga 100. Nilai default adalah 20.

Parameter respons

data array[object]

Daftar item pesan.

Properti

id string

ID unik item pesan.

content string atau array

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

role string

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

status string

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

type string

Tipe item pesan. Nilainya tetap 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_id string

ID item pesan pertama dalam daftar.

has_more boolean

Menunjukkan apakah masih ada data tambahan.

last_id string

ID item pesan terakhir dalam daftar.

object string

Tipe objek. Nilainya tetap 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_id string (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",
)

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'

item_id string (Wajib, Path)

ID item pesan.

Parameter respons

content array[object]

Daftar konten pesan yang berisi satu atau lebih objek konten.

Properti

type string

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

text string

Konten teks.

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

id string

ID unik item pesan.

role string

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

status string

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

type string

Tipe item pesan. Nilainya tetap 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_id string (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.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'

item_id string (Wajib, Path)

ID item pesan.

Parameter respons

deleted boolean

Menunjukkan apakah item berhasil dihapus.

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

id string

ID item pesan yang dihapus.

object string

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

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.7-plus",
  input: "How old is Alice?"
});
console.log("First response:", response1.output_text);

const response2 = await client.responses.create({
  conversation: conversation.id,
  model: "qwen3.7-plus",
  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.