> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Dreamina Videos

> Dreamina API guide - Ace Data Cloud

## API de generación de videos de personas digitales de Dreamina

`POST https://api.acedata.cloud/dreamina/videos`

Generación de videos de personas digitales impulsados por audio (OmniHuman 1.5). Proporcione una foto de la persona y un audio de conducción para generar un video en el que la persona hable y sincronice los movimientos de la boca.

### Encabezados de solicitud

| Encabezado | Valor |
| - | - |
| `Authorization` | `Bearer <tu API Key>` |
| `Content-Type` | `application/json` |

### Parámetros de solicitud

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `model` | string | No | Modelo, por defecto `omnihuman-1.5` |
| `image_url` | string | Sí | URL pública de la foto de la persona, se recomienda que sea clara y de frente |
| `audio_url` | string | Sí | URL pública del audio de conducción (mp3/wav), se recomienda \< 60 segundos |
| `prompt` | string | No | Controla la expresión, emoción, estabilidad y estilo |
| `mask_url` | string\[] | No | URL de máscara del sujeto, utilizada para especificar el objeto de conducción en imágenes con múltiples personas |
| `callback_url` | string | No | Si se proporciona, devuelve inmediatamente `task_id`, y después de generar el resultado, llama a esta dirección |
| `async` | boolean | No | Si se establece en `true`, devuelve inmediatamente `task_id`, sin necesidad de `callback_url`, consulta el resultado a través de `/dreamina/tasks` |

### Sugerencias de entrada

* **Imagen**: Efecto de retrato frontal claro y bien iluminado es el mejor; la cara debe estar despejada y ocupar una proporción adecuada en la imagen.
* **Audio**: mp3/wav, debe ser accesible públicamente. Se recomienda que la duración esté controlada dentro de 60 segundos (1080p se recomienda ≤30 segundos, 720p ≤60 segundos).
* Tanto `image_url` como `audio_url` deben ser accesibles públicamente.

### Ejemplo de respuesta

```json theme={null}
{
  "success": true,
  "task_id": "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": {
    "task_id": "362b4fed67bd11f1ad1100163e57d510",
    "status": "done",
    "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }
}
```

### Asincronía y consulta

La interfaz devuelve por defecto el video final de forma sincrónica. Para tareas más largas, se pueden utilizar uno de los dos modos asíncronos:

* Proporcionar `callback_url`: la interfaz devuelve inmediatamente `task_id`, y después de generar el resultado, llama a esta dirección.
* Proporcionar `async: true`: la interfaz devuelve inmediatamente `task_id`, luego consulta el resultado a través de `POST /dreamina/tasks` (gratis) por `task_id` o `trace_id`.

Para más detalles sobre la consulta, consulte [Dreamina Tasks API](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

### Manejo de errores

| Código de estado | código | Significado |
| - | - | - |
| 400 | `bad_request` | Parámetros faltantes o inválidos (como `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | Token de autorización faltante o inválido |
| 403 | `forbidden` | Saldo/cuota insuficiente, o no autorizado por el proveedor |
| 429 | `too_many_requests` | Demasiadas solicitudes, excede el límite de velocidad |
| 500 | `api_error` | Error interno del servidor |

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "image_url is required (a public URL of a portrait image)"
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### Facturación

Se cobra según la duración del video generado, el paquete máximo es aproximadamente **¥1/segundo** (por ejemplo, un video de 10 segundos cuesta aproximadamente ¥10).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.