Skip to main content

HappyOyster-Directing-Query Travel Status APIリファレンス

Directing Travelのライフサイクル、サーバー側のストリーミングステータス、実行済みのテキスト指示、およびチャプター情報をクエリします。同時にクライアントのプルストリームまたは再生ハートビートを報告することもできます。

スコープ

Directing Travelのライフサイクル、サーバー側のストリーミングステータス、実行済みのテキスト指示、およびチャプター情報をクエリします。同時にクライアントのプルストリームまたは再生ハートビートを報告することもできます。呼び出し前に、以下を確認してください：
  • 認証：プライマリ API キーは必須ではありません。プライマリまたは一時 API キーのいずれかで呼び出せます。取得方法については、認証情報の取得 を参照してください。
  • 前提条件：Enter Travel によって返された encryptedTravelId を使用してクエリします。
  • 呼び出し元：サーバーまたはクライアントのいずれからも呼び出すことができます。2〜5秒ごとにポーリングすることをお勧めします。

HTTP リクエスト

  • Singapore
  • 米国（バージニア）
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/travels/status{WorkspaceId} を実際の ワークスペースID に置き換えます。

リクエストパラメーター

  • Travelステータスのクエリ
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/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 （必須）Directing暗号化済みTravel IDです。Travelへの入室によって返されます。
clientStreamStatus string （任意）クライアントのRTCプルストリームまたは再生ステータスです。大文字小文字は区別されません。認識できない値は無視されます。許可される値は以下の通りです。
  • DISCONNECTED：未接続またはチャネルから退出済み
  • CONNECTING：RTCチャネルに接続中
  • CONNECTED：参加済みですが、再生が開始されていないか、最初のフレームが到着していません
  • PLAYING：リモートストリームを受信済みでレンダリング中
  • BUFFERING：バッファリング中
  • PAUSED：クライアントが再生を一時停止しました。これはサーバー側のpauseとは異なります。
  • RECONNECTING：再接続中
clientStreamStatusTimeMs long （任意）クライアントの状態変更のミリ秒タイムスタンプです。clientStreamStatusと一緒に使用します。

レスポンスパラメーター

  • Travel実行中
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "running",
        "rtcStatus": "PUSHING",
        "updateTime": "2026-06-04T00:02:00Z",
        "userInstructions": [
            {
                "instruction": "A giant robotic dinosaur suddenly appears",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Chapter 1",
                "brief": "The detective enters the cyberpunk city",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}
code integerリターンコード。0 は成功を意味し、ゼロ以外の値はエラーコードです。
message stringエラーメッセージ。成功時は null です。
data objectレスポンスデータ。失敗時は null です。

プロパティ

encryptedTravelId string暗号化されたTravel ID。status stringTravelライフサイクルステータス：
  • init：セッションリソースを初期化中
  • pending：キューに入っているか、サービスリソースを待機中
  • running：実行中。作成サブモードに応じて、サポートされている制御エンドポイントを呼び出すことができます。
  • paused：サーバー側の一時停止が完了しました。再開または巻き戻しが可能です。
  • failed：Travel が失敗しました。
  • completed：Travelが終了しました。アーティファクトをクエリできます
rtcStatus stringサーバー側のRTCストリーミングステータスです。クライアントが報告するclientStreamStatusとは異なります。updateTime string最終更新時刻です。ISO 8601形式です。userInstructions arrayテキスト指示のリスト。データがない場合はnullです。各項目にはinstruction、relativeStartTimeMs / relativeEndTimeMs（相対ミリ秒）、startTime / endTime（タイムライン秒）、およびstatusが含まれます。chapters arrayチャプターリスト。チャプター検出がまだトリガーされていない場合はnullです。各項目にはchapterId、title、brief、actRange、startTime、endTime、およびchapterImageが含まれます。characterActions arrayDirectingモデルでは空の配列に固定されています。environmentActions arrayDirectingモデルでは空の配列に固定されています。

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

  • 2〜5秒ごとにポーリングしてください。
  • runningステータスでは、creationModelに応じてサポートされている制御エンドポイントを呼び出すことができます。標準モードはinstruct、pause、resume、rewind、およびendをサポートし、スクリプトモードはupdate-script、pause、resume、rewind、およびendをサポートします。
  • このエンドポイントはmode、aspectRatio、playUrl、bgmUrl、またはsessionIdを返しません。ストリーミング設定はEnter Travelのレスポンスに基づきます。
  • clientStreamStatusはクライアント側の再生ハートビートであり、rtcStatusはサーバー側のストリーミングステータスです。これらは互換性がありません。

エラーコード

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

次のステップ

Travelがrunningまたはpausedの場合：