Skip to main content

HappyOyster-Acting-Query Travel Artifacts APIリファレンス

完了した Acting Travel の記録済みオリジナルと3つの合成バリアントをクエリします。外部への配信には withInstructionAndWatermark を推奨します。

スコープ

完了した Acting Travel の記録済みオリジナルと3つの合成バリアントをクエリします。withInstruction はユーザーのプロセス指示のオーバーレイバリアントです。外部への配信には withInstructionAndWatermark を推奨します。呼び出す前に、以下を確認してください。
  • 認証：プライマリ API Key のみがサポートされています。一時的な API Key は使用できません（エラーコード 403003）。
  • 前提条件：Travelのステータスがcompletedであること。利用可能なオリジナルURLがアーティファクトレスポンスを返すための前提条件となります。Query Travel Statusで確認してください。
  • Caller：サーバーから呼び出されます。

HTTP リクエスト

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

リクエストパラメーター

  • Travelアーティファクトのクエリ
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/travels/artifacts?encryptedTravelId={encryptedTravelId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
Authorization string （必須）API Key 認証。プライマリ API Key のみがサポートされており、sk- で始まります（例：sk-xxx）。通常、環境変数 $DASHSCOPE_API_KEY として設定されます。一時的な API Key（st- で始まる）を使用すると 403003 が返されます。
クエリパラメータ
encryptedTravelId string （必須）ステータスがcompletedのActing暗号化Travel IDです。Enter Travelによって返されます。

レスポンスパラメーター

  • 4つのアーティファクトすべてが準備完了
  • 合成処理中
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "composeStatus": "ready",
        "video": {
            "original": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_raw.mp4?v=2",
                "status": "ready",
                "resolution": "720p",
                "durationSec": 180
            },
            "withWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_wm.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstruction": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_overlay.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            },
            "withInstructionAndWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_all.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 180
            }
        }
    }
}
code integerリターンコード。0 は成功を意味し、ゼロ以外の値はエラーコードです。
message stringエラーメッセージ。成功時は null です。
data objectレスポンスデータ。失敗時は null です。

プロパティ

encryptedTravelId string暗号化されたTravel ID。composeStatus string3つの合成バリアントの集約ステータス：
  • ready：withWatermark、withInstruction、およびwithInstructionAndWatermarkがすべてreadyです
  • partial：少なくとも1つの合成バリアントが ready ですが、すべてではありません。
  • processing：3つの合成バリアントのうち ready であるものが none もありません。
これは3つの合成バリアントのみを集約しており、original は含みません。video objectメインビデオの4つの固定バリアントです。各項目には url、status、resolution、および durationSec が含まれます。
  • original：記録されたオリジナル。利用可能な場合は720p表現が優先的に返されます
  • withWatermark：ウォーターマークのみの合成バリアント
  • withInstruction：ユーザーの処理指示オーバーレイを含む合成バリアント
  • withInstructionAndWatermark：ユーザーの処理指示オーバーレイ＋ウォーターマーク合成バリアント。外部配信に推奨されます
video.*.url stringダウンロードURL。processing または unavailable の場合は null となります。video.*.status string項目ごとのステータス：
  • ready：準備完了、urlにアクセス可能
  • processing：合成処理中、url=null
  • unavailable：合成に失敗したか、URLが一時的に利用できません、url=null
video.*.resolution stringoriginal が 720p と一致する場合は "720p" となります。それ以外の場合は null となる可能性があります。video.*.durationSec integer秒単位の統一されたビデオ再生時間です。解析可能な場合、すべての ready バリアントがこの値を持ちます。processing / unavailable の場合、または再生時間がまだ解析できない場合は null となる可能性があります。

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

  • クライアントは、composeStatus != readyの間、制御された間隔でポーリングできます。
  • video.withInstructionは処理指示オーバーレイバリアントであり、指示なしのオリジナルではありません。
  • 外部配信の場合はvideo.withInstructionAndWatermarkを参照してください。ビジネスでオリジナルのみが必要な場合は、引き続きvideo.original.urlを参照してください。
  • 4つのビデオバリアントは同じ再生時間解析結果を共有するため、1つのレスポンス内で解析可能な再生時間を持つ準備完了のバリアントは一貫した durationSec を返します。
  • TRAVEL_NO_STREAM_AUTO_ENDによって終了されたTravelはfailedとなり、クエリ可能なアーティファクトを生成しません。
  • 404000 を常に「未完了」としてレンダリングしないでください。まず Query Travel Status または Query Travel List を通じて status と errorCode を読み取ってください。failed の Travel については、失敗理由を表示してください。
404000 シナリオ
シナリオエンドポイントの動作
Travelがまだ進行中（init / pending / running / paused)ビジネスコード 404000を返します（ message = Video is still being generated, please try again once the process is complete
Travelが failedビジネスコード 404000を返します（ message = Experience failed and no video was produced (errorCode=<errorCode>): <errorMessage>。失敗は終端状態であり、動画は生成されません
Travelが存在しない、自分のものではない、またはActingではないビジネスコード 404000
オリジナルURLが利用不可ビジネスコード 404000。オリジナルはエンドポイント全体のハードゲートです
オリジナルは準備完了だが合成はまだ処理中HTTP 200。対応する合成アイテムは status=processing, url=null
合成に失敗したか、URLが一時的に利用不可HTTP 200。対応する合成アイテムは status=unavailable, url=null

エラーコード

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

次のステップ

  • Query Travel List：他の過去のTravelを表示します。
  • End Travel：アーティファクトをクエリする前に新しいTravelを終了します。