Skip to main content

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

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

スコープ

完了した Adventure Travel の記録済みオリジナルと3つの合成バリアントをクエリします。Adventure において、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-adventure/openapi/v1/travels/artifacts{WorkspaceId} を実際の ワークスペースID に置き換えます。

リクエストパラメーター

  • Travelアーティファクトのクエリ
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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 の Adventure 暗号化 Travel ID です。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": 90
            },
            "withWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_wm.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 90
            },
            "withInstruction": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_overlay.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 90
            },
            "withInstructionAndWatermark": {
                "url": "https://cdn.happyoyster.com/exports/trvl_a1b2c3d4e5f6_all.mp4?v=2",
                "status": "ready",
                "resolution": null,
                "durationSec": 90
            }
        }
    }
}
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 となる可能性があります。

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

  • Travel が completed でない場合、存在しない場合、あなたのものでないか Adventure でない場合、またはオリジナルがまだ利用できない場合は、404000 が返されます。オリジナルはこのエンドポイント全体のハードゲートです。
  • クライアントは、composeStatus != readyの間、制御された間隔でポーリングできます。
  • withInstruction を演出用テキスト字幕として解釈しないでください。Adventure では、これは探索インタラクションオーバーレイです。
  • 外部配信の場合はvideo.withInstructionAndWatermarkを参照してください。ビジネスでオリジナルのみが必要な場合は、引き続きvideo.original.urlを参照してください。
  • 4つのビデオバリアントは同じ再生時間解析結果を共有するため、1つのレスポンス内で解析可能な再生時間を持つ準備完了のバリアントは一貫した durationSec を返します。
  • TRAVEL_NO_STREAM_AUTO_ENDによって終了されたTravelはfailedとなり、クエリ可能なアーティファクトを生成しません。

エラーコード

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

次のステップ

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