HappyOyster-Directing-Query Travel Status APIリファレンス - Alibaba Cloud Model Studio

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

米国（バージニア）

GET https://{WorkspaceId}.us-east-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 string

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

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 array

Directingモデルでは空の配列に固定されています。

environmentActions array

Directingモデルでは空の配列に固定されています。

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

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の場合：

標準モード：プロセス指示の送信。
スクリプトモード：フルスクリプト更新。
共通：一時停止 / 再開 / 巻き戻し / 終了。