HappyOyster-Acting-Create World API リファレンス - Alibaba Cloud Model Studio

ロールプレイ World を作成します。自然言語プロンプトと必須の最初のフレーム画像から World を作成します。API は暗号化された World ID（encryptedWorldId）を即座に返し、World はバックグラウンドで非同期に構築され、クライアントは構築が完了するまで進捗状況をポーリングします。

スコープ

Acting World を作成します。呼び出す前に、以下を確認してください：

認証：プライマリ API Key のみがサポートされています。一時的な API Key は使用できません（エラーコード 403003）。
- プライマリ API Key を取得する：API Key の取得と設定。
呼び出しモード：非同期モードを推奨します。
- 非同期モード（デフォルト）：async=true の場合、API は即座に encryptedWorldId を返します。進捗状況については World 構築ステータスのクエリをポーリングしてください。
- 同期モード：async=false の場合、サーバーは内部でポーリングを行い（3 秒ごと、最大 120 秒）、構築が完了すると応答を返します。タイムアウト時は非同期にフォールバックし、クライアントがポーリングを継続します。
エンドポイントの制限：このエンドポイントは Acting World のみを作成できます。mode を渡す必要はありません（サーバーが 3 を書き込みます。3 以外の値を渡すと 400000 が返されます）。creationModel は常に simple であり、uploadMode は first_frame に固定され、入室バージョンは actingV2 に固定されています。

HTTP リクエスト

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds

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

米国（バージニア）

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

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

リクエストパラメーター

最初のフレーム画像（非同期）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "prompt": "A blonde girl with twin tails, a white bow, and a golden crescent crown on her forehead; a white shirt with a navy sailor collar and a blue bow tie, and a blue-and-white argyle short skirt. Her right hand holds up a yellow sticky note that reads \"Good night\". Behind her are a deep-red velvet curtain and a cluster of flowers. Facing the camera, an anime-realistic blend, warm indoor lighting.",
    "resolution": "480p",
    "aspectRatio": "9:16",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc5.png",
        "referenceType": "default"
    }
}'

最初のフレーム画像 base64（非同期）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "prompt": "A relaxed conversation on the living-room sofa, with the character naturally looking toward the camera",
    "resolution": "480p",
    "aspectRatio": "9:16",
    "firstFrameImage": {
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
        "referenceType": "default"
    }
}'

Content-Typestring（必須）

リクエストのコンテンツタイプ。このパラメータは application/json に設定する必要があります。

Authorization string （必須）

API Key 認証。プライマリ API Key のみがサポートされており、sk- で始まります（例：sk-xxx）。通常、環境変数 $DASHSCOPE_API_KEY として設定されます。一時的な API Key（st- で始まる）を使用すると 403003 が返されます。

リクエストボディ

async boolean（オプション）

非同期で作成するかどうか。デフォルトは true です：

true：即座に応答を返します。World はバックグラウンドで構築され、クライアントは World 構築ステータスのクエリをポーリングします。
false：サーバーは 3 秒ごとに最大 120 秒間ポーリングし、構築が完了すると応答を返します。タイムアウト時も generating を返し、その後クライアントが独自にポーリングを行います。

creationModel string（オプション）

作成サブモード。デフォルトは simple です。Acting では simple のみがサポートされています。

prompt string （必須）

キャラクター、シーン、および演技目標の自然言語による説明。空ではなく、最大 2000 文字までです。欠落、空白、または長さ超過の場合は 400000 が返されます。

uploadMode string（オプション）

画像アップロードモード。デフォルトは first_frame です。Acting では first_frame のみがサポートされています。

resolution string（オプション）

ビデオ解像度。デフォルトは 480p です。許可される値：

480p
720p

aspectRatio string（オプション）

ストリーミングフレーム比率。これは最初のフレーム画像の向きも決定します。両者を一致させることを推奨します。デフォルトは 9:16 です。許可される値：

9:16（縦向き）：縦向きの最初のフレームを推奨します
16:9（横向き）：横向きの最初のフレームを推奨します

つまり、縦向きストリーミング（9:16）の場合は縦向きの最初のフレームを渡し、横向きストリーミング（16:9）の場合は横向きの最初のフレームを渡します。デフォルトは 9:16 です。横向きが必要な場合は、明示的に aspectRatio=16:9 を渡す必要があります。

refWorldId string（オプション）

既存の Acting World から新しい作成物を派生させます。現在のプライマリアカウント配下の Acting 暗号化 World ID である必要があります。別のモデルまたは別のプライマリアカウントの World を指定すると 403001 が返されます。

firstFrameImage object （必須）

World の最初のフレームとして再利用される画像参照。url と base64 は排他的です（いずれか一方を選択）。画像の制約事項：

フォーマット：JPG / JPEG / PNG / WebP
サイズ：画像ごとに厳密に 6 MB 未満
アスペクト比：aspectRatio=9:16 の場合、幅 / 高さは 0.5–0.667 です。aspectRatio=16:9 の場合は 1.5–2.0 です
コンテンツ安全性：コンテンツ安全性または著作権 / IP 検証に失敗すると、403004 / 403005 が返されます

プロパティ

url string（条件付き必須）

最初のフレーム画像の URL。base64 とは排他的です（いずれか一方を選択）。制約事項：

ホストを含む有効な http / https URL であり、サーバーからアクセス可能である必要があります
実際のフォーマット、サイズ、および最初のフレームのアスペクト比は、保存後に検証されます
非同期リクエストは最初に generating を返すことがあり、その後画像検証の失敗により World が failed 状態になります

base64 string（条件付き必須）

最初のフレーム画像の base64。url とは排他的です（いずれか一方を選択）。制約事項：

完全なデータ URI data:image/<subtype>;base64,<payload> を推奨します
フォーマット、サイズ、および最初のフレームのアスペクト比は、作成エントリーポイントで同期的に検証されます

referenceType string（オプション）

最初のフレーム参照タイプ。デフォルトは default で、現在は default として使用されています。

レスポンスパラメーター

非同期作成

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}

リクエスト失敗

{
    "code": 400000,
    "message": "Invalid request parameters.",
    "data": null
}

code integer

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

message string

エラーメッセージ。成功時は null、失敗時は人間が読める形式のエラーメッセージです。

data object

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

プロパティ

encryptedWorldId string

サーバーによって生成された暗号化された World ID。同期モードと非同期モードの両方で返されます。後続の構築ステータスポーリング、詳細クエリ、および Travel Credential の交換に使用されます。

status string

現在の作成ステータス：

generating: 構築中
ready: 準備完了
failed: 構築失敗

firstFrame string

World の最初のフレームの URL。生成前は null です。

エラーコード

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

次のステップ

作成成功後、以下の操作が可能です：

World 構築ステータスのクエリ：World が ready 状態になるまで、3～5 秒ごとにポーリングします。
World が ready 状態になった後、Travel Credential の取得を呼び出して、使い捨ての ticket と交換します。
World 詳細のクエリ：完全な作成メタデータをクエリします。