> ## 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

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

오디오 기반의 디지털 인물 구술 비디오 생성(OmniHuman 1.5). 인물 사진과 드라이브 오디오를 제공하여 인물이 입을 열고 말하는, 입 모양이 동기화된 비디오를 생성합니다.

### 요청 헤더

| 헤더 | 값 |
| - | - |
| `Authorization` | `Bearer <당신의 API Key>` |
| `Content-Type` | `application/json` |

### 요청 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 아니오 | 모델, 기본값 `omnihuman-1.5` |
| `image_url` | string | 예 | 인물 사진의 공개 URL, 선명한 정면 사진을 권장 |
| `audio_url` | string | 예 | 드라이브 오디오의 공개 URL(mp3/wav), 60초 미만을 권장 |
| `prompt` | string | 아니오 | 표정, 감정, 안정성 및 스타일 제어 |
| `mask_url` | string\[] | 아니오 | 주체 마스크 URL, 다수 인물 사진에서 드라이브 대상을 지정하기 위해 |
| `callback_url` | string | 아니오 | 전달 시 즉시 `task_id`를 반환하며, 결과 생성 후 해당 주소로 콜백 |
| `async` | boolean | 아니오 | `true`로 설정 시 즉시 `task_id`를 반환하며, `callback_url`이 필요 없고 `/dreamina/tasks`를 통해 결과를 폴링 |

### 입력 제안

* **사진**: 선명하고 조명이 좋은 정면 인물 사진이 최적; 얼굴이 가려지지 않고 화면에서 적당한 비율을 차지해야 합니다.
* **오디오**: mp3/wav, 공개적으로 접근 가능해야 합니다. 권장 길이는 60초 이내(1080p는 ≤30초, 720p는 ≤60초).
* `image_url`과 `audio_url`은 모두 공개적으로 접근 가능해야 합니다.

### 응답 예시

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

### 비동기 및 조회

인터페이스는 기본적으로 최종 비디오를 동기적으로 반환합니다. 긴 작업의 경우 두 가지 비동기 모드 중 하나를 사용할 수 있습니다:

* `callback_url`을 전달: 인터페이스가 즉시 `task_id`를 반환하며, 결과 생성 후 해당 주소로 콜백합니다.
* `async: true`를 전달: 인터페이스가 즉시 `task_id`를 반환하며, 이후 `POST /dreamina/tasks`(무료)를 통해 `task_id` 또는 `trace_id`로 결과를 폴링합니다.

폴링 계약에 대한 자세한 내용은 [Dreamina Tasks API](https://platform.acedata.cloud/documents/dreamina-tasks-integration)를 참조하십시오.

### 오류 처리

| 상태 코드 | 코드 | 의미 |
| - | - | - |
| 400 | `bad_request` | 파라미터 누락 또는 유효하지 않음(예: `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | 인증 토큰 누락 또는 유효하지 않음 |
| 403 | `forbidden` | 잔액/쿼터 부족, 또는 상위에서 권한 없음 |
| 429 | `too_many_requests` | 요청이 너무 많아 속도 제한 초과 |
| 500 | `api_error` | 서버 내부 오류 |

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

### 요금

생성된 비디오의 길이에 따라 요금이 부과되며, 최대 요금은 약 **¥1/초**입니다(예: 10초 비디오 약 ¥10).


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