Skip to main content
Referensi Open API Adventure

Referensi API HappyOyster-Adventure-Enter Travel

Klien menggunakan ticket untuk membuat Travel aktual dan mendapatkan konfigurasi bergabung RTC serta versi kapabilitas Adventure. maxExperienceTimeSec hanya berlaku pada model Adventure.

Cakupan

Klien menggunakan ticket untuk membuat Travel aktual dan mendapatkan konfigurasi bergabung RTC. maxExperienceTimeSec hanya berlaku pada model Adventure. Sebelum memanggil, pastikan hal berikut:
  • Autentikasi: API KeyAPI Key utama tidak wajib; ticket menyelesaikan validasi masuk room. Untuk cara mendapatkannya, lihat Mendapatkan kredensial autentikasi.
  • Prasyarat: ticket diperoleh dari Dapatkan Kredensial Travel, belum kedaluwarsa dan belum digunakan, serta status World-nya adalah ready.
  • Pemanggil: Dipanggil oleh klien Anda.

Permintaan HTTP

  • Singapore
  • Tiongkok (Beijing)
  • AS (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travelGanti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya.

Parameter permintaan

  • Masuk travel (klien)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}",
    "maxExperienceTimeSec": 90
}'
Content-Typestring(Wajib)Tipe konten permintaan. Parameter ini harus diatur ke application/json.
Authorization string (Wajib)Autentikasi Kunci API. Kunci API utama tidak wajib; kunci API utama atau sementara dapat digunakan untuk memanggilnya.
  • API Key Utama: dimulai dengan sk-, misalnya sk-xxx.
  • Kunci API Sementara: diawali dengan st-, misalnya st-xxx.
Request Body
ticket string (Wajib)Kredensial sekali pakai yang belum kedaluwarsa dan belum digunakan, yang diperoleh dari Dapatkan Kredensial Travel. Menggunakan ulang ticket yang sama akan mengembalikan 401011.
maxExperienceTimeSec integer (Opsional)Durasi pengalaman maksimum, dalam detik, harus berupa integer JSON. Defaultnya adalah 60. Nilai yang diizinkan:
  • 60
  • 90
  • 120
String dan nilai numerik lainnya tidak diterima (misalnya "60" tidak valid); tingkatan yang tidak valid akan mengembalikan 400000. Server secara otomatis mengakhiri Travel setelah durasi ini tercapai.

Parameter respons

  • Berhasil masuk
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 1,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "wanderV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": 90
    }
}
code integerKode pengembalian. 0 berarti berhasil; bukan nol adalah kode kesalahan.
message stringPesan kesalahan. null jika berhasil.
data objectData respons. null jika gagal.

Properti

encryptedTravelId stringID Travel terenkripsi yang baru dibuat. Digunakan untuk kueri Kueri Status Travel, pengakhiran, dan artefak selanjutnya.encryptedWorldId stringID World terenkripsi yang sesuai dengan Travel ini.mode integerSelalu 1 untuk Adventure.creationModel stringSelalu simple untuk Adventure.playUrl nullBelum tersedia; ditetapkan ke null.firstFrame stringURL frame pertama World.rtcConfig objectKonfigurasi bergabung RTC; bernilai null ketika tidak ada channel streaming yang tersedia, sehingga klien tidak dapat memulai pemutaran berdasarkan konfigurasi tersebut.
  • channelId: ID channel RTC
  • appId: ID aplikasi RTC yang ditetapkan oleh platform
  • token: Token bergabung RTC
  • userId: ID pengguna bergabung RTC, ditetapkan ke user_1
version stringVersi enter-room Adventure, ditetapkan ke wanderV2. Data kontrol harus dikirim melalui SDK sendCommand sesuai dengan versi ini.aspectRatio nullDitetapkan ke null untuk Adventure; rasio aspek pemutar tidak dibaca dari bidang ini dan mengikuti rasio gambar bingkai pertama.noStreamAutoEndTimeoutSec integerBatas waktu pengakhiran otomatis tanpa stream dalam detik, defaultnya 30; respons aktual yang berlaku. Jika rtcStatus tidak memasuki status streaming dalam waktu ini setelah masuk ke room, panggil Akhiri Travel dengan failCode=TRAVEL_NO_STREAM_AUTO_END.maxExperienceTimeSec integerDurasi pengalaman yang benar-benar diterapkan oleh server; hanya bisa berupa 60 / 90 / 120. Server secara otomatis mengakhiri Travel setelah durasi ini tercapai.

Status prasyarat dan catatan pemanggilan

  • World yang sesuai dengan ticket harus berstatus ready, dan tiket harus belum kedaluwarsa serta belum digunakan.
  • Pemanggilan yang berhasil akan membuat Travel; menggunakan ulang ticket yang sama akan mengembalikan 401011.
  • version harus ditangani sebagai wanderV2; jangan mengirim data kontrol menggunakan protokol interaksi model lain.
  • Server mengakhiri pengalaman setelah maxExperienceTimeSec tercapai; klien harus menangani status akhir yang diterima setelahnya.
  • Kontrol arah, sudut pandang, dan tindakan Adventure bukanlah Open API HTTP sisi server; klien harus menggunakan sendCommand dari SDK platform yang sesuai, yang dikirimkan SDK melalui DataChannel RTC.
  • rtcConfig=null berarti saat ini tidak ada channel streaming yang tersedia, sehingga klien tidak dapat memulai pemutaran berdasarkan konfigurasi tersebut.

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan kesalahan, lihat Kode Kesalahan HappyOyster untuk menyelesaikannya.

Langkah selanjutnya

Setelah berhasil masuk ke room:
  • Kueri Status Travel: lakukan polling setiap 2–5 detik untuk membaca kumpulan tindakan yang tersedia.
  • Setelah Travel menjadi running, klien mengirimkan kontrol arah, sudut pandang, dan tindakan melalui SDK sendCommand.
  • Akhiri Travel: akhiri sesi dan tangani artefaknya.
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