Skip to main content
Toolkit/Framework

OpenAI-compatible - Percakapan

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
Jalur URL lama /api/v2/apps/protocols/compatible-mode/v1/conversations segera tidak akan didukung lagi. Segera migrasikan ke jalur baru /compatible-mode/v1/conversations.
Alibaba 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)

Parameter respons

created_atintegerTimestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.idstringID unik percakapan.metadataobjectMetadata 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.objectstringTipe 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)

Parameter respons

created_atintegerTimestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.idstringID unik percakapan.metadataobjectMetadata 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.objectstringTipe 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)

Parameter respons

created_atintegerTimestamp Unix dalam milidetik yang menunjukkan kapan percakapan dibuat.idstringID unik percakapan.metadataobjectMetadata 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.objectstringTipe 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)

Parameter respons

deletedbooleanMenunjukkan apakah penghapusan berhasil.idstringID percakapan yang dihapus.objectstringTipe 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)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.
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)

Parameter respons

dataarray[object]Daftar item pesan yang dibuat.

Properties

idstringID unik item pesan.contentstring or arrayKonten pesan. Ini dapat berupa string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText.rolestringPeran pesan. Nilai yang valid adalah user, assistant, system, dan developer.statusstringStatus pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.typestringTipe item pesan. Nilainya tetap message.
first_idstringID item pesan pertama dalam daftar.has_morebooleanMenunjukkan apakah masih ada data lain yang tersedia.last_idstringID 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)

Parameter respons

dataarray[object]Daftar item pesan.

Properties

idstringID unik item pesan.contentstring or arrayKonten pesan. Ini dapat berupa string teks biasa atau daftar konten terstruktur, seperti array objek ResponseInputText.rolestringPeran pesan. Nilai yang valid adalah user, assistant, system, dan developer.statusstringStatus pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.typestringTipe item pesan. Nilainya tetap message.
first_idstringID item pesan pertama dalam daftar.has_morebooleanMenunjukkan apakah masih ada data lain yang tersedia.last_idstringID item pesan terakhir dalam daftar.objectstringTipe 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)

Parameter respons

contentarray[object]Daftar konten pesan yang berisi satu atau lebih objek konten.

Properties

typestringTipe konten, seperti input_text untuk teks input pengguna atau output_text untuk teks output model.textstringKonten teks.
idstringID unik item pesan.rolestringPeran pesan. Nilai yang valid adalah user, assistant, system, dan developer.statusstringStatus pemrosesan pesan. Nilai yang valid adalah in_progress, completed, dan incomplete.typestringTipe 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)

Parameter respons

deletedbooleanMenunjukkan apakah item berhasil dihapus.idstringID item pesan yang dihapus.objectstringTipe 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}")

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.
Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model