Crear un mundo de juego de roles. Cree un mundo a partir de un prompt en lenguaje natural y una imagen de primer fotograma requerida; la API devuelve inmediatamente un ID de mundo cifrado (encryptedWorldId), el mundo se construye asíncronamente en segundo plano y el cliente sondea el progreso de la construcción hasta que finaliza.
Ámbito
Crear un mundo de Acting. 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 mundo de Acting. No necesita pasar mode (el servidor escribe 3; pasar un valor distinto de 3 devuelve 400000). creationModel siempre es simple, uploadMode está fijado en first_frame, y la versión de entrada a la sala está fijada en actingV2.
Solicitud HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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-acting/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-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 de imagen del primer fotograma (asíncrono)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(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. |
creationModel string (Opcional) Submodo de creación. El valor predeterminado es simple; Acting solo admite simple. |
prompt string (Obligatorio) Una descripción en lenguaje natural del personaje, la escena y el objetivo de la actuación. No vacía, hasta 2000 caracteres. Si falta, está en blanco o excede la longitud, devuelve 400000. |
uploadMode string (Opcional) Modo de carga de imagen. El valor predeterminado es first_frame; Acting solo admite first_frame. |
resolution string (Opcional) Resolución de video. El valor predeterminado es 480p. Valores permitidos: |
aspectRatio string (Opcional) Relación de fotogramas de transmisión, que también determina la orientación de la imagen del primer fotograma; se recomienda mantener ambas consistentes. El valor predeterminado es 9:16. Valores permitidos:
9:16 (vertical): se recomienda un primer fotograma vertical16:9 (horizontal): se recomienda un primer fotograma horizontal Es decir, para transmisión vertical (9:16) pase un primer fotograma vertical, y para transmisión horizontal (16:9) pase un primer fotograma horizontal. El valor predeterminado es 9:16; cuando se necesita horizontal, debe pasar explícitamente aspectRatio=16:9. |
refWorldId string (Opcional) Derivar una nueva creación de un mundo de Acting existente. Debe ser un ID de mundo cifrado de Acting bajo la cuenta principal actual; un mundo de otro modelo u otra cuenta principal devuelve 403001. |
firstFrameImage object (Requerido) Una referencia de imagen reutilizada como 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: cuando
aspectRatio=9:16, ancho / alto es 0.5–0.667; cuando aspectRatio=16:9, es 1.5–2.0
- 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 referencia del primer fotograma. 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
}
}
Error en la solicitud{
"code": 400000,
"message": "Invalid request parameters.",
"data": 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; un mensaje de error legible por humanos en caso de fallo. |
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 actual de la creación:
generating: construyendoready: listofailed: error de construcción 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: