HappyOyster-Adventure-旅行ステータスクエリAPIリファレンス - Alibaba Cloud Model Studio

Adventure旅行のライフサイクル、サーバー側のストリーミングステータス、および現在のワールドのアクションプールをクエリします。同時にクライアントのプルストリームまたは再生ハートビートを報告することも可能です。

スコープ

Adventure旅行のライフサイクル、サーバー側のストリーミングステータス、および現在のワールドのアクションプールをクエリします。同時にクライアントのプルストリームまたは再生ハートビートを報告することも可能です。呼び出し前に以下を確認してください:

認証：プライマリ API キーは必須ではありません。プライマリまたは一時 API キーのいずれかで呼び出せます。取得方法については、認証情報の取得を参照してください。
前提条件：Enter Travel によって返された encryptedTravelId を使用してクエリします。
呼び出し元：サーバーまたはクライアントのいずれからも呼び出すことができます。2〜5秒ごとにポーリングすることをお勧めします。

HTTP リクエスト

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status

{WorkspaceId} を実際のワークスペースID に置き換えます。

中国（北京）

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status

{WorkspaceId} を実際のワークスペースID に置き換えます。

米国（バージニア）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status

{WorkspaceId} を実際のワークスペースID に置き換えます。

リクエストパラメーター

Travelステータスのクエリ

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/status?encryptedTravelId={encryptedTravelId}&clientStreamStatus=PLAYING&clientStreamStatusTimeMs=1788940800000' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Authorization string （必須）

API キー認証です。プライマリ API キーは必須ではなく、プライマリまたは一時 API キーのいずれかで呼び出せます。

プライマリ API Key：sk- で始まります（例：sk-xxx）。
一時 API キー：st- で始まり、例は st-xxx です。

クエリパラメータ

encryptedTravelId string （必須）

Adventureの暗号化された旅行IDです。旅行に入るによって返されます。

clientStreamStatus string （任意）

クライアントのRTCプルストリームまたは再生ステータスです。大文字小文字は区別されません。認識できない値は無視されます。許可される値は以下の通りです。

DISCONNECTED：未接続またはチャネルから退出済み
CONNECTING：RTCチャネルに接続中
CONNECTED：参加済みですが、再生が開始されていないか、最初のフレームが到着していません
PLAYING：リモートストリームを受信済みでレンダリング中
BUFFERING：バッファリング中
PAUSED: クライアント側で再生が一時停止されました。これはAdventure Travelがサーバー側の一時停止をサポートしていることを意味するものではありません。
RECONNECTING：再接続中

clientStreamStatusTimeMs long （任意）

クライアントの状態変更のミリ秒タイムスタンプです。clientStreamStatusと一緒に使用します。

レスポンスパラメーター

Travel実行中

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-06-04T00:02:00Z",
        "userInstructions": null,
        "chapters": null,
        "characterActions": [
            "dash",
            "jump",
            "crouch",
            "attack"
        ],
        "environmentActions": [
            "ride_motorcycle",
            "enter_exit_car"
        ]
    }
}

code integer

リターンコード。0 は成功を意味し、ゼロ以外の値はエラーコードです。

message string

エラーメッセージ。成功時は null です。

data object

レスポンスデータ。失敗時は null です。

プロパティ

encryptedTravelId string

暗号化されたTravel ID。

status string

Travelライフサイクルステータス：

init：セッションリソースを初期化中
pending：キューに入っているか、サービスリソースを待機中
running: 実行中。SDKのsendCommandを通じてリアルタイム制御が可能です。
failed：Travel が失敗しました。
completed：Travelが終了しました。アーティファクトをクエリできます

Adventureプロダクト機能にはpaused状態はありません。一時停止/再開を中心としたステートマシンを構築しないでください。

rtcStatus string

サーバー側のRTCストリーミングステータスです。クライアントが報告するclientStreamStatusとは異なります。

updateTime string

最終更新時刻です。ISO 8601形式です。

userInstructions null | array

AdventureはHTTP instructをサポートしておらず、探索アクションはこのフィールドに反映されません。通常はnullまたは[]となり、無視して構いません。

chapters array

チャプターリスト。チャプターデータが未生成の場合はnullとなります。

characterActions array

現在のキャラクター/主体に対して利用可能なアクションID。推奨がない場合は[]となります。通常、2〜4個が返されます。主なアクション:

dash: 前方ダッシュ
jump: ジャンプ
crouch: しゃがむ / うつ伏せになる
attack: 攻撃

environmentActions array

現在のシーンで利用可能な環境インタラクションアクションID。推奨がない場合は[]となります。サーバーはシーンに基づき固定アクションプールから0〜3個を選択し、空の配列を返すこともあります。主なアクション:

ride_horse: 馬に乗る
ride_bicycle: 自転車に乗る
ride_motorcycle: オートバイに乗る
enter_exit_car: 車に乗降する
open_close_door: ドアを開閉する
take_cover: 隠れる
car_light: 車のライトを点灯する。enter_exit_carも返される場合にのみ表示されることがあります。
car_horn: クラクションを鳴らす。enter_exit_carも返される場合にのみ表示されることがあります。

前提条件となるステータスと呼び出しに関する注意事項

2〜5秒ごとにポーリングしてください。
Adventureプロダクト機能にはpaused状態はありません。一時停止/再開を中心としたステートマシンを構築しないでください。
characterActionsおよびenvironmentActionsは利用可能なアクションのヒントです。実際の制御は引き続きSDKのsendCommandを通じて送信されます。
このエンドポイントはmode、playUrl、bgmUrl、またはsessionIdを返しません。ストリーミング設定はEnter Travelのレスポンスに基づきます。
clientStreamStatusはクライアント側の再生ハートビートであり、rtcStatusはサーバー側のストリーミングステータスです。これらは互換性がありません。
AdventureはHTTP instruct、pause、resume、rewind、またはupdate-scriptをサポートしていません。以下のパスを利用可能なHTTP機能として統合しないでください: /travels/instruct、/travels/pause、/travels/resume、/travels/rewind、/travels/update-script。

エラーコード

モデルの呼び出しに失敗してエラーが返された場合は、HappyOyster エラーコードを参照して解決してください。

次のステップ

旅行がrunningになった後:

クライアントはSDKのsendCommandを通じて方向、視点、およびアクション制御を送信します（まずこのエンドポイントから返されるアクションプールを確認できます）。
Travel の終了：セッションを終了し、成果物を処理します。