Skip to main content

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

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 に置き換えます。

リクエストパラメーター

  • 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 stringTravelライフサイクルステータス：
  • init：セッションリソースを初期化中
  • pending：キューに入っているか、サービスリソースを待機中
  • running: 実行中。SDKのsendCommandを通じてリアルタイム制御が可能です。
  • failed：Travel が失敗しました。
  • completed：Travelが終了しました。アーティファクトをクエリできます
Adventureプロダクト機能にはpaused状態はありません。一時停止/再開を中心としたステートマシンを構築しないでください。rtcStatus stringサーバー側のRTCストリーミングステータスです。クライアントが報告するclientStreamStatusとは異なります。updateTime string最終更新時刻です。ISO 8601形式です。userInstructions null | arrayAdventureは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 の終了：セッションを終了し、成果物を処理します。