Skip to main content

Referencia de la API HappyOyster-Acting-Create World

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
  • EE. UU. (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worldsReemplace {WorkspaceId} con su ID de espacio de trabajo real.

Parámetros de solicitud

  • Imagen del primer fotograma (asíncrono)
  • 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 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"
    }
}'
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:
  • 480p
  • 720p
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 vertical
  • 16: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
  • Error en la solicitud
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}
code integerCódigo de retorno. 0 indica éxito; un valor distinto de cero es un código de error.
message stringMensaje de error. null en caso de éxito; un mensaje de error legible por humanos en caso de fallo.
data objectDatos de respuesta. null en caso de fallo.

Propiedades

encryptedWorldId stringEl 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 stringEstado actual de la creación:
  • generating: construyendo
  • ready: listo
  • failed: error de construcción
firstFrame stringURL 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: