Skip to main content

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

完了したDirecting Travelの録画オリジナルおよび3つの合成バリアントをクエリします。利用可能なオリジナルが存在することがアーティファクトレスポンスを返す前提条件です。外部配信にはwithInstructionAndWatermarkが推奨されます。

スコープ

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

HTTP リクエスト

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

リクエストパラメーター

  • Travelアーティファクトのクエリ
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/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のDirecting暗号化済み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": 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 object4つのメインライン動画アーティファクトで、固定のフィールド構造を持ちます。各項目にはurl、status、resolution、およびdurationSecが含まれます。
  • original：録画されたオリジナル。720pの表現が推奨されます。
  • withWatermark：ウォーターマークのみの合成バリアント
  • withInstruction：ユーザー指示の字幕のみを含む合成バリアント。
  • withInstructionAndWatermark：ユーザー指示の字幕とウォーターマークを含む合成バリアント。外部配信に推奨されます。
video.*.url string動画URL。status=processingの場合はnullです。video.*.status string項目ごとのステータス：
  • ready：動画の準備ができており、URLにアクセス可能です。
  • processing：処理中。urlはnullです。
  • unavailable：合成に失敗したか、URLが一時的に利用できません。
video.*.resolution stringオリジナルが720pと一致する場合、video.original.resolutionは"720p"になります。それ以外の場合はnullです。video.*.durationSec integer秒単位の統一されたビデオ再生時間です。解析可能な場合、すべての ready バリアントがこの値を持ちます。processing / unavailable の場合、または再生時間がまだ解析できない場合は null となる可能性があります。

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

  • Travelがcompletedでない、存在しない、あなたのものでない、Directingではない、またはオリジナルが利用できない場合、404000が返されます。利用可能なオリジナルが存在することが、アーティファクトレスポンスを返すための前提条件です。
  • すべての合成バリアントが必要な場合は、composeStatus != readyの間ポーリングを続けることができます。
  • 外部配信にはvideo.withInstructionAndWatermarkが推奨されるバリアントです。
  • 4つのビデオバリアントは同じ再生時間解析結果を共有するため、1つのレスポンス内で解析可能な再生時間を持つ準備完了のバリアントは一貫した durationSec を返します。

エラーコード

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

次のステップ

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