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

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

スコープ

Acting 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-acting/openapi/v1/travels/status

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

米国（バージニア）

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

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

リクエストパラメーター

Travelステータスのクエリ

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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 （必須）

Acting暗号化Travel IDです。Enter 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-09-09T08:30:00Z",
        "userInstructions": [
            {
                "instruction": "Greet with a smile and ask how my day is going",
                "relativeStartTimeMs": 12000,
                "relativeEndTimeMs": 16000,
                "startTime": 12.0,
                "endTime": 16.0,
                "status": "executed"
            }
        ],
        "chapters": [
            {
                "chapterId": 1,
                "title": "Greeting",
                "brief": "The character smiles at the camera and starts the conversation",
                "actRange": [0, 10],
                "startTime": 4,
                "endTime": 20,
                "chapterImage": "https://cdn.happyoyster.com/chapters/acting_ch1.jpg"
            }
        ],
        "characterActions": [],
        "environmentActions": []
    }
}

Travel失敗

errorCode の値については Error codes を参照してください。

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "status": "failed",
        "rtcStatus": null,
        "updateTime": null,
        "userInstructions": null,
        "chapters": null,
        "characterActions": null,
        "environmentActions": null,
        "errorCode": "TRAVEL_SESSION_INIT_FAILED",
        "errorMessage": "Failed to allocate inference resources."
    }
}

code integer

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

message string

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

data object

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

プロパティ

encryptedTravelId string

暗号化されたTravel ID。

status string

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

init：セッションリソースを初期化中
pending：キューに入っているか、サービスリソースを待機中
running：実行中。テキスト指示の送信、一時停止、または終了が可能です
paused：サーバー側で一時停止中。テキスト指示の送信、再開、または終了が可能です
failed：Travelが失敗しました。理由についてはerrorCode／errorMessageを参照してください
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<string> | null

Acting は SDK アクション制御をサポートしていません。空の配列を返します。failed の場合は null となります。

environmentActions array<string> | null

Acting は SDK 環境アクション制御をサポートしていません。空の配列を返します。failed の場合は null となります。

errorCode string

status=failedの場合にのみ返される構造化された失敗理由コードです。値についてはエラーコードを参照してください。

errorMessage string

errorCode と一緒に返される英語の失敗説明です。errorMessage ではなく errorCode に基づいて分岐してください。

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

2〜5秒ごとのポーリングを推奨します。
runningとpausedの両方でSend Process Instructionの呼び出しが可能です。paused状態で指示を送信しても、Travelは自動的には再開されません。
このエンドポイントはmode、aspectRatio、playUrl、bgmUrl、またはsessionIdを返しません。ストリーミング設定とプレーヤーの向きは、Enter Travelのレスポンスに基づきます。
clientStreamStatusはクライアント側の再生ハートビートであり、rtcStatusはサーバー側のストリーミングステータスです。これらは互換性がありません。
Acting は SDK の sendCommand をサポートしていません。2つの空のアクション配列に基づいて演出やアクション制御を構築しないでください。
failedは終端状態であり、動画は生成されません。errorCodeに基づいて失敗理由を表示し、「未完了」として表示しないでください。

エラーコード

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

次のステップ

Travelがrunningまたはpausedの場合：

Send Process Instruction：後続のキャラクターパフォーマンスを駆動します。
Pause Travel／Resume Travel。
End Travel：終了後にアーティファクトをクエリします。