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

リアルタイムディレクティングワールドを作成します。標準モード（自然言語プロンプト）とスクリプトモード（構造化ScriptList）をサポートしており、APIは暗号化されたワールドIDを即座に返し、ワールドはバックグラウンドで非同期にビルドされ、クライアントは完了までビルド進捗をポーリングします。

スコープ

ディレクティングワールドを作成します。呼び出す前に、以下を確認してください。

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

HTTP リクエスト

Singapore

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

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

米国（バージニア）

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

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

標準モード（`creationModel=simple`）

リクエストパラメーター

標準モード・プレーンテキスト（非同期作成）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "First-person (POV) interactive video: the camera simulates my own eyes, locked on a white Maltese puppy directly in front of me — white chef's hat, black-buttoned chef's coat. Soft home-kitchen background, warm light, the puppy's gaze always facing the camera.",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'

標準モード・テキスト＋参照画像（非同期作成）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "A café by the window. A young woman with long black hair, wearing a beige turtleneck sweater, sits sideways, her left hand propping up her chin as she gazes at the rain-speckled glass window. On the wooden table sits a cup of steaming dark coffee. Outside, warm-yellow street lamps glow in the rainy night; indoors, a single pendant lamp. A quiet rainy night.",
    "resolution": "720p",
    "inputImages": [
        {
            "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
            "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を渡してください。自然言語のpromptを提供すると、サーバーが完全な45ビートのスクリプト、最初のフレーム（ユーザーが提供することも可能）、およびキャラクター参照画像を生成します。ワールド作成後、トラベルフェーズ中に以下の制御エンドポイントを呼び出すことができます。

instruct：テキストによるプロセス指示を送信
pause：一時停止
resume：再開
rewind：巻き戻し
end：終了

各エンドポイントの説明については、補足事項を参照してください。

eventStyle string （任意）

creationModel=simpleにのみ適用されます：スクリプト生成テンプレートを選択します。デフォルトはnormalです。許容値：

normal：通常／標準スタイル（デフォルト）。ユーザーの意図に従って比較的安定したペースで4～5幕を完結させ、対立、逆転、または三幕構成のクライマックスを強制しません。
dramatic：ドラマチック／対立スタイル。おおよそ180秒の三幕構成（導入のフック、対立の高まり、転換点、クライマックスでの解決）に基づいてスクリプトを生成します。オープンエンドのパフォーマンスでは、ジャンル（ミステリー／スリラー／復活劇など）に応じて逆転を配置し、より高密度なペースと強いドラマ性を備えます。
regular：レガシー値で、過去の入力との後方互換性のためにのみ保持されています。サーバーはこれをnormalとして解析します。新しい呼び出しでは使用しないでください。

refWorldId string （任意）

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

prompt string （必須）

ワールドのテーマ説明。中国語と英語に対応しています。空ではなく、最大2000文字です。

resolution string （必須）

動画解像度。許容値：

480p
720p

layout string （任意）

カメラムーブメントスタイル（カメラの動き方とカットの強さ）。許容値：

Stable：安定したカメラで動きが少なく、カットの少ない連続したロングテイクを重視します。
Fast：高速なカメラワークで勢いがあり、ハードカット／素早いズーム／ショットサイズの変更がより頻繁になります。
Calm：両者の中間で、急ぎすぎず攻撃的でもない抑制されたカメラワークです。

narrative string （任意）

ナラティブスタイル（ドラマの密度と感情の強さ）。許容値：

Calm：イベントが少なく、雰囲気とゆっくりとした進行を重視
Dramatic：イベントが密集しており、反応／逆転／障害がより顕著で緊張感が高くなります。
Normal：通常のナラティブ密度、中間レベル
Steady：クライマックスが積み重ならない均等なペース、Normalに近い

firstFrameImage object （任意）

提供された場合、ワールドの最初のフレームとして直接再利用され、AIによる初回フレーム生成はスキップされます。urlとbase64は排他的（いずれか一方を選択）です。画像の制約：

フォーマット：JPG / JPEG / PNG / WebP
サイズ：画像ごとに厳密に 6 MB 未満
アスペクト比：横長である必要があり、幅 / 高さは 1.5–2.0 です（フレーム比率はこの画像に従います）。
コンテンツ安全性：コンテンツ安全性または著作権 / IP 検証に失敗すると、403004 / 403005 が返されます

プロパティ

url string （条件付き必須）

最初のフレーム画像URL。制約事項：

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

base64 string （条件付き必須）

最初のフレーム画像base64。制約事項：

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

referenceType string （任意）

参照画像タイプ。デフォルトはdefaultです。

inputImages array （任意）

スクリプト生成およびキャラクター参照画像に使用され、最大6枚の画像を指定でき、firstFrameImageとは独立しています。各配列項目について、urlとbase64は排他的（いずれか一方を選択）です。画像の制約：

フォーマット：JPG / JPEG / PNG / WebP
サイズ：画像ごとに厳密に 6 MB 未満
アスペクト比：横長である必要があり、幅 / 高さは 1.5–2.0 です（フレーム比率はこの画像に従います）。
コンテンツ安全性：コンテンツ安全性または著作権 / IP 検証に失敗すると、403004 / 403005 が返されます

プロパティ

url string （条件付き必須）

画像URL。制約事項：

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

base64 string （条件付き必須）

画像base64。制約事項：

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

referenceType string （任意）

参照画像タイプ。デフォルトはdefaultです。

スクリプトモード（`creationModel=scriptlist`）

リクエストパラメーター

スクリプトモード（非同期作成）

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "scriptlist",
    "resolution": "720p",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
        "referenceType": "default"
    },
    "scriptList": {
        "videoTitle": "Su Nian · Sitting with You for a While Tonight",
        "synopsis": "The young girl Su Nian sits at a light-colored desk facing the camera, chatting with you slowly and helping you let go of the day.",
        "subjects": [
            {
                "label": "[character_1]",
                "name": "Su Nian",
                "type": "character",
                "gender": "female",
                "age": "young girl",
                "ethnicity": "East Asian",
                "appearance": "medium-length straight black hair with a side part, a rounded face, a cream-white knit top, anime style, clean lines",
                "position": "center of the frame, seated at a light-colored desk",
                "voice": "gentle girlish voice, slightly slow pace, moderate volume"
            }
        ],
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] sits at the light-colored desk facing the camera, leaning slightly forward, eyes curving as she softly says, \"Hey, I'll sit with you for a while again tonight, let's chat slowly.\"",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] folds her hands on the desk, nods gently, and says, \"Let's set aside all the worries of the day for now.\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 3,
                "content": "[character_1] tilts her head slightly, looking at the camera with a gentle expression, and asks, \"How was your day? Are you okay, are you tired?\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'

Content-Typestring（必須）

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

Authorization string （必須）

リクエストボディ

async boolean （任意）

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

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

creationModel string （任意）

作成サブモード。スクリプトモードの場合はscriptlistを渡してください。構造化されたスクリプトを提供すると、サーバーはスクリプトを生成せず、組み立てと永続化のみを行います。ワールド作成後、トラベルフェーズ中に以下の制御エンドポイントを呼び出すことができます。

update-script：スクリプトを完全に置き換える
pause：一時停止
resume：再開
rewind：巻き戻し
end：終了

instruct（テキストプロセス指示の送信）はサポートされていません。各エンドポイントの説明については、補足事項を参照してください。

注記

eventStyleはスクリプトリスト作成では使用されないため、渡さないでください。

refWorldId string （任意）

resolution string （必須）

動画解像度。許容値：

480p
720p

firstFrameImage object （必須）

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

フォーマット：JPG / JPEG / PNG / WebP
サイズ：画像ごとに厳密に 6 MB 未満
アスペクト比：横長である必要があり、幅 / 高さは 1.5–2.0 です（フレーム比率はこの画像に従います）。
コンテンツ安全性：コンテンツ安全性または著作権 / IP 検証に失敗すると、403004 / 403005 が返されます

プロパティ

url string （条件付き必須）

最初のフレーム画像URL。制約事項：

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

base64 string （条件付き必須）

最初のフレーム画像base64。制約事項：

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

referenceType string （任意）

参照画像タイプ。デフォルトはdefaultです。

scriptList object （必須）

構造化スクリプト。synopsisと空でないactsを含める必要があります。

プロパティ

synopsis string （必須）

ストーリーのあらすじ。空でないこと、最大2000文字。

videoTitle string （任意）

ワールド名。デフォルトはNew World、最大128文字。

scene string （任意）

シーンの設定。デフォルトはStatic Shot、最大64文字。

style string （任意）

ビジュアルスタイル。デフォルトはStable、最大64文字。

speed string （任意）

ナラティブのペース。デフォルトはSteady、最大64文字。

language string （任意）

スクリプト言語。デフォルトはen（英語）です。中国語の場合はzhを渡してください。最大64文字です。

setting string （任意）

世界観または背景設定。最大2000文字。

soundtrack string （任意）

サウンドトラックの説明。最大500文字。

prologue string （任意）

オープニングプロローグ。最大1000文字。

videoTags array<string> （任意）

動画タグ。最大20個のタグ、各タグは最大32文字。

subjects array<object> （任意）

事前定義された被写体で、最大6個まで指定できます。各配列項目には以下のプロパティが含まれます。

subjects[]のプロパティ

label string （任意）

acts[].content内の被写体を参照します。[character_x]という形式で、デフォルトでは配列順に割り当てられます。

name string （任意）

人間が読める名前であり、画面テキストとしてはレンダリングされません。最大64文字です。

type string （任意）

被写体のタイプ。デフォルトはcharacterです。被写体の外観および他のプロパティの入力方法を決定します。許容値：

character：人間のキャラクター（デフォルト）。人物と同様にgender / position / ethnicity / age / appearanceを入力してください。
animal：実在する動物（猫、犬、馬など）。性別の代わりに種別を、民族の代わりに亜種／品種を使用してください。
creature：非人間／ファンタジー生物（ドラゴン、モンスター、エイリアンなど）。非人間の外観についても同様に入力してください。
narrator：ナレーター／ボイスオーバー。音声のみで画面には表示されません。voiceを入力すると参照画像は生成されません。

refImage object （任意）

被写体の参照画像。urlとbase64は排他的（いずれか一方を選択）であり、画像は厳密に6 MB未満である必要があります。

refImageのプロパティ

url string （条件付き必須）

被写体参照画像URL。

base64 string （条件付き必須）

被写体参照画像base64。

referenceType string （任意）

参照画像タイプ。デフォルトはdefaultです。

gender string （任意）

性別の説明。最大64文字。

position string （任意）

画面上の位置。最大64文字。

ethnicity string （任意）

民族または人種の説明。最大64文字。

age string （任意）

年齢の説明。最大64文字。

appearance string （任意）

外見の詳細。最大500文字。

voice string （任意）

声、話す速さ、音量の説明。最大200文字。

acts array<object> （必須）

ビートごとのスクリプトで、1～45エントリ、すべてのcontentの合計は100000文字以内です。各配列項目には以下のプロパティが含まれます。

acts[]のプロパティ

turn int （任意）

ターン番号。1～45の範囲で重複不可、デフォルトでは配列順に1からインクリメントされます。

content string （必須）

このビートのスクリプトです。空ではなく、ビートあたり最大2000文字で、[character_x]を使用して被写体を参照できます。

cameraType string （任意）

カメラタイプ（カメラの撮影方法）。デフォルトはStaticです。許容値：

Static：カメラが固定され、プッシュやスイベルはありません（デフォルト）。ショットサイズはshotSizeによって制御されます：wide / medium / close
Tracking：トラッキングショット。カメラが被写体を追いかけ、追跡距離を維持します。
Pan Left：カメラを固定して左にパン
Pan Right：カメラを固定して右にパン
Tilt Up：カメラを上に向ける
Tilt Down：カメラを下に向ける
Push-in：光学/物理プッシュイン、フレームが徐々に近づく
Pull-out：プルアウト、フレームが徐々に広くなる
POV Forward：一人称視点、カメラが目となり前方へ歩く
POV Look Down：一人称視点で見下ろす
POV Look Up：一人称視点で見上げる
POV Turn Left：一人称視点で左を向く
POV Turn Right：一人称視点で右を向く

shotSize string （任意）

ショットサイズ。デフォルトはMediumです。このビートで表現できる詳細度を決定します。カットを通じてショットサイズを変更し、同じビート内で全身と指先の両方を記述しないでください。許容値：

Wide：ワイド／フルショットで、全身とその環境との関係を含みます。ブロッキング、ポジショニング、空間演出に適していますが、微細な表情や指先は記述しないでください。
Medium：ミディアムショット（デフォルト）で、上半身の姿勢やジェスチャーを含みます。会話や日常動作に適していますが、足の運びや細かな手の操作は記述しないでください。
Close-up：クローズアップで、顔1つ／手1つ／小道具1つを対象とします。表情や重要な詳細に適していますが、全身の動きは記述しないでください。

カットとの組み合わせ：詳細を確認するには、まずcut-inでClose-upにし、次にcut-outでワイドショットに戻ります。ほとんどのビートでlong-takeを使用して同じショットサイズを維持し、ショットサイズの頻繁な切り替えを避けてください。

cut string （任意）

カット方法（このビートのカットイン方法）。デフォルトはlong-takeです。許容値：

long-take：カットなしで、前のショットから継続します。デフォルトかつ最も安定しています。
hard-cut：ハードカットで、瞬時に別のショットに切り替えます。ショット／リバースショットの会話に使用してください。
cut-in：より近いショットサイズにカットします。例：Medium → Close-up。詳細の確認や手のインタラクションへのカットインに使用してください。
cut-out：より広いショットサイズにカットします。例：Close-up → Medium / Wide
cutaway：メインライン外のディテールへの短いカット
cutback：cutawayからメインの被写体にカットバックします。cutawayの後にのみ使用できます。
camera movement transition：ハードカットではなく、素早いカメラムーブメントで2つのセグメントを接続します。

レスポンスパラメーター

非同期作成

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

code integer

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

message string

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

data object

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

プロパティ

encryptedWorldId string

暗号化されたワールドIDで、同期モードと非同期モードの両方で返されます。この値は、後続のビルドステータス照会、ワールド詳細照会、および体験クレデンシャルの交換に使用されます。

status string

現在の作成ステータス：

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

firstFrame string

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

補足事項

文字数カウント：本文書における「最大N文字」の制限は、中国語か英語かに関係なく文字（Unicode文字）単位でカウントされます。漢字、英字、数字、スペース、句読点はそれぞれ1文字としてカウントされます。
ScriptList提出要件：ワールド作成時、actsは45エントリに制限されますが、正確に45である必要はありません。完全な45エントリが必要なのは、トラベル中にupdate-scriptを呼び出す場合のみです。
トラベル制御エンドポイント：creationModelの下にリストされているエンドポイント名は、ワールド作成後のトラベルフェーズ中に呼び出すことができるサーバーサイドのエンドポイントであり、このエンドポイント入力の列挙値ではありません。その意味は以下の通りです。
- instruct：実行中のトラベルにテキストプロセス指示を送信します。標準モード専用です。
- pause：トラベルを一時停止します。
- resume：再生を再開します。
- rewind：指定された时间点へ巻き戻します。事前に一時停止が必要です。
- end：トラベルを終了します。
- update-script：スクリプトを完全に置換します。スクリプトモード専用です。

エラーコード

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

次のステップ

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

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

スコープ

HTTP リクエスト

Singapore

米国（バージニア）

標準モード（creationModel=simple）

リクエストパラメーター

標準モード・プレーンテキスト（非同期作成）

標準モード・テキスト＋参照画像（非同期作成）

リクエストボディ

スクリプトモード（creationModel=scriptlist）

リクエストパラメーター

スクリプトモード（非同期作成）

リクエストボディ

レスポンスパラメーター

非同期作成

補足事項

エラーコード

次のステップ

標準モード（`creationModel=simple`）

スクリプトモード（`creationModel=scriptlist`）