> ## 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 Geração de Vídeo de Pessoa Digital

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

Geração de vídeo de pessoa digital impulsionada por áudio (OmniHuman 1.5). Forneça uma foto da pessoa e um áudio de impulso para gerar um vídeo da pessoa falando, com sincronia labial.

### Cabeçalho da Requisição

| Cabeçalho | Valor |
| - | - |
| `Authorization` | `Bearer <sua chave API>` |
| `Content-Type` | `application/json` |

### Parâmetros da Requisição

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `model` | string | Não | Modelo, padrão `omnihuman-1.5` |
| `image_url` | string | Sim | URL pública da foto da pessoa, recomenda-se que seja clara e de frente |
| `audio_url` | string | Sim | URL pública do áudio de impulso (mp3/wav), recomenda-se \< 60 segundos |
| `prompt` | string | Não | Controla a expressão, emoção, estabilidade e estilo |
| `mask_url` | string\[] | Não | URL do mask do sujeito, usado para especificar o objeto de impulso em imagens com várias pessoas |
| `callback_url` | string | Não | Se fornecido, retorna imediatamente `task_id`, e o resultado é retornado a esse endereço após a geração |
| `async` | boolean | Não | Se definido como `true`, retorna imediatamente `task_id`, sem necessidade de `callback_url`, e consulta o resultado através de `/dreamina/tasks` |

### Sugestões de Entrada

* **Imagem**: Efeitos de retrato frontal claros e bem iluminados são os melhores; o rosto deve estar desobstruído e ocupar uma proporção adequada na imagem.
* **Áudio**: mp3/wav, deve ser acessível publicamente. Recomenda-se que a duração seja controlada em até 60 segundos (1080p recomenda-se ≤30 segundos, 720p ≤60 segundos).
* `image_url` e `audio_url` devem ser acessíveis publicamente.

### Exemplo de Resposta

```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"
  }
}
```

### Assíncrono e Consulta

A interface retorna o vídeo final de forma síncrona por padrão. Para tarefas mais longas, você pode usar um dos dois modos assíncronos:

* Fornecer `callback_url`: a interface retorna imediatamente `task_id`, e o resultado é retornado a esse endereço após a geração.
* Fornecer `async: true`: a interface retorna imediatamente `task_id`, e depois consulta o resultado através de `POST /dreamina/tasks` (gratuito) usando `task_id` ou `trace_id`.

O contrato de consulta pode ser encontrado na [API de Tarefas Dreamina](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

### Tratamento de Erros

| Código de Status | Código | Significado |
| - | - | - |
| 400 | `bad_request` | Parâmetros ausentes ou inválidos (como `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | Token de autorização ausente ou inválido |
| 403 | `forbidden` | Saldo/limite insuficiente, ou não autorizado por upstream |
| 429 | `too_many_requests` | Muitas solicitações, excedendo o limite de taxa |
| 500 | `api_error` | Erro interno do 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"
}
```

### Cobrança

A cobrança é feita com base na duração do vídeo gerado, com o pacote máximo em torno de **¥1/segundo** (por exemplo, um vídeo de 10 segundos custa cerca de ¥10).


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