Cree un mundo de exploración mundial. Cree un mundo a partir de un prompt en lenguaje natural y una imagen de primer fotograma obligatoria; la API devuelve inmediatamente un ID de mundo cifrado, el mundo se construye de forma asíncrona en segundo plano y el cliente sondea el progreso de la construcción hasta que se completa.
Ámbito
Cree un Adventure World. Antes de realizar la llamada, confirme lo siguiente:
-
Autenticación: Solo se admite la API Key principal; no se pueden utilizar API Keys temporales (código de error 403003).
-
Modo de llamada: Se recomienda el modo asíncrono.
- Modo asíncrono (predeterminado):
async=true, la API devuelve inmediatamente encryptedWorldId; sondee Consultar estado de construcción del mundo para verificar el progreso.
- Modo síncrono:
async=false, el servidor sondea internamente (cada 3s, hasta 120s) y devuelve cuando finaliza la construcción; si se agota el tiempo de espera, vuelve al modo asíncrono y el cliente continúa sondeando.
-
Restricciones del endpoint: Este endpoint solo puede crear un Adventure World. No necesita pasar mode (el servidor escribe 1; pasar un valor distinto de 1 devuelve 400000). creationModel siempre es simple, uploadMode está fijo en first_frame, y la versión de entrada a la sala está fija en wanderV2.
Solicitud HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
EE. UU. (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Parámetros de solicitud | Imagen del primer fotograma (asíncrono)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"
}
}'
Base64 de imagen del primer fotograma (asíncrono)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": {
"base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
}'
|
Content-Typestring(Requerido) Tipo de contenido de la solicitud. Este parámetro debe establecerse en application/json. |
Authorization string (Requerido) Autenticación mediante API Key. Solo se admite la API Key principal; comienza con sk-, p. ej., sk-xxx. Normalmente se configura como la variable de entorno $DASHSCOPE_API_KEY. Una API Key temporal (que comienza con st-) devuelve 403003. |
Cuerpo de la solicitud |
async boolean (Opcional) Indica si se debe crear de forma asíncrona. El valor predeterminado es true:
true: devuelve inmediatamente; el mundo se construye en segundo plano y el cliente sondea Consultar estado de construcción del mundo.false: el servidor sondea cada 3 segundos durante un máximo de 120 segundos y devuelve cuando finaliza la construcción; si se agota el tiempo de espera, aún devuelve generating, y el cliente continúa sondeando por su cuenta. |
perspective string (Obligatorio) Perspectiva. Valores permitidos:
first_person: primera personathird_person: tercera persona Omitir este campo devuelve 400000. |
prompt string (Obligatorio) Descripción del tema del mundo; se admiten chino e inglés. No vacío, hasta 2000 caracteres. Si falta, está en blanco o excede la longitud, devuelve 400000. |
creationModel string (Opcional) Submodo de creación. El valor predeterminado es simple; Adventure solo admite simple. |
uploadMode string (Opcional) Modo de carga de imagen. El valor predeterminado es first_frame; Adventure solo admite first_frame. |
refWorldId string (Opcional) Derive una nueva creación de un Adventure World existente. Debe ser un ID de mundo cifrado de Adventure bajo la cuenta principal actual; un mundo de otro modelo u otra cuenta principal devuelve 403001. |
firstFrameImage object (Requerido) Una referencia de imagen reutilizada directamente como el primer fotograma del mundo. url y base64 son mutuamente excluyentes (elija uno). Restricciones de imagen:
- Formato: JPG / JPEG / PNG / WebP
- Tamaño: estrictamente menor que 6 MB por imagen
- Relación de aspecto: debe ser horizontal, ancho / alto de 1.5–2.0 (la relación del fotograma sigue esta imagen)
- Seguridad del contenido: si falla la verificación de seguridad del contenido o de derechos de autor / propiedad intelectual, devuelve
403004 / 403005
Propiedades url string (Condicionalmente requerido) URL de la imagen del primer fotograma. Mutuamente excluyente con base64 (elija uno). Restricciones:
- Debe ser una URL
http / https válida con un host, accesible por el servidor
- El formato, tamaño y relación de aspecto del primer fotograma reales se validan después del almacenamiento
- Una solicitud asíncrona puede devolver primero
generating, luego el mundo entra en failed debido a un fallo en la validación de la imagen
base64 string (Condicionalmente requerido) Base64 de la imagen del primer fotograma. Mutuamente excluyente con url (elija uno). Restricciones:
- Se recomienda un URI de datos completo
data:image/<subtype>;base64,<payload>
- El formato, tamaño y relación de aspecto del primer fotograma se validan sincrónicamente en el punto de entrada de creación
referenceType string (Opcional) Tipo de imagen de referencia. El valor predeterminado es default, y actualmente se utiliza como default. |
Parámetros de respuesta | Creación asíncrona{
"code": 0,
"message": null,
"data": {
"encryptedWorldId": "enc_a1b2****",
"status": "generating",
"firstFrame": null
}
}
|
code integer Código de retorno. 0 indica éxito; un valor distinto de cero es un código de error. |
message string Mensaje de error. null en caso de éxito. |
data object Datos de respuesta. null en caso de fallo. Propiedades encryptedWorldId string El ID de mundo cifrado generado por el servidor. Devuelto tanto en modos síncronos como asíncronos; utilizado para sondeos posteriores del estado de construcción, consultas de detalles e intercambio de credenciales de viaje. status string Estado de creación actual: generating (construyendo) o ready; también puede ser failed cuando falla una construcción síncrona. firstFrame string URL del primer fotograma del mundo; null antes de que se genere. |
Códigos de error
Si la llamada al modelo falla y devuelve un error, consulte Códigos de error de HappyOyster para resolverlo.
Siguientes pasos
Después de crear con éxito, puede: