Skip to main content

HappyOyster-Adventure-Create World API リファレンス

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

スコープ

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

HTTP リクエスト

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

リクエストパラメーター

  • 最初のフレーム画像（非同期）
  • 最初のフレーム画像 base64（非同期）
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
    }
}'
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 を返し、その後クライアントが独自にポーリングを行います。
perspective string （必須）視点。許可される値：
  • first_person：一人称
  • third_person：三人称
このフィールドを省略すると 400000 が返されます。
prompt string （必須）World のテーマ説明。中国語および英語がサポートされています。空ではなく、最大 2000 文字までです。欠落、空白、または長さ超過の場合は 400000 が返されます。
creationModel string（オプション）作成サブモード。デフォルトは simple です。Adventure では simple のみがサポートされています。
uploadMode string（オプション）画像アップロードモード。デフォルトは first_frame です。Adventure では first_frame のみがサポートされています。
refWorldId string（オプション）既存の Adventure World から新しい作成物を派生させます。現在のプライマリアカウント配下の Adventure 暗号化 World ID である必要があります。別のモデルまたは別のプライマリアカウントの World を指定すると 403001 が返されます。
firstFrameImage object （必須）World の最初のフレームとして直接再利用される画像参照です。url と base64 は排他的です（いずれか一方を選択してください）。画像の制約事項：
  • フォーマット：JPG / JPEG / PNG / WebP
  • サイズ：画像ごとに厳密に 6 MB 未満
  • アスペクト比：横長である必要があり、幅 / 高さは 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 integerリターンコード。0 は成功を意味し、ゼロ以外の値はエラーコードです。
message stringエラーメッセージ。成功時は null です。
data objectレスポンスデータ。失敗時は null です。

プロパティ

encryptedWorldId stringサーバーによって生成された暗号化された World ID。同期モードと非同期モードの両方で返されます。後続の構築ステータスポーリング、詳細クエリ、および Travel Credential の交換に使用されます。status string現在の作成ステータス：generating（構築中）または ready。同期構築が失敗した場合は failed になることもあります。firstFrame stringWorld の最初のフレームの URL。生成前は null です。

エラーコード

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

次のステップ

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