# 음성과 이미지 다루기

> **이 장에서 배우는 것**
> 음성·이미지 경로를 어떻게 쓰는지, 그리고 여기서만 되는 것 하나.

## 왜 따로 다루나

[앞 장](/guide/ht-model-api)의 대화·임베딩은 결과가 **글**입니다. 음성과 이미지는
결과가 **파일**이라 다루는 방식이 다릅니다.

- 응답이 큽니다 (wav, png)
- 시간이 오래 걸립니다
- **결과를 어디에 저장할지**를 정해야 합니다

## 글 → 음성

```bash
curl -X POST http://localhost:27777/api/ai/v1/audio/speech \
  -H "Authorization: Bearer $HT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<모델 이름>",
    "input": "안녕하세요. 오늘 소식을 전해드립니다.",
    "voice": "<목소리>"
  }' \
  --output out.wav
```

**`--output`을 빠뜨리면 터미널에 이진 데이터가 쏟아집니다.** 흔한 실수입니다.

### 긴 글은 나눠서

한 번에 긴 글을 넣으면 오래 걸리고 중간에 실패하면 처음부터입니다. **문단
단위로 나눠 만들고 이어붙이는** 쪽이 안정적입니다.

```
✗ 원고 전체를 한 번에
✓ 문단별로 wav 생성 → 파일 목록 → 이어붙이기
```

이어붙이는 것은 [터미널](/guide/ht-terminal)에서 오디오 도구로 하면 됩니다.

## 음성 → 글

```bash
curl -X POST http://localhost:27777/api/ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $HT_KEY" \
  -F file=@meeting.m4a \
  -F model="<모델 이름>"
```

**회의 녹음을 회의록으로 만드는 파이프라인**의 첫 단계입니다.

```mermaid
graph TD
  A["녹음 파일"] --> B["음성 → 글"]
  B --> C["원문 텍스트"]
  C --> D["업무로 넘김<br/>'실행 항목 표로 정리'"]
  D --> E["회의록"]
```

두 번째 단계는 [REST로 업무](/guide/ht-rest-api)를 만들면 됩니다. 이렇게
**모델 API와 업무 API를 잇는 것**이 실무에서 가장 자주 쓰는 형태입니다.

## 복제 목소리 — 여기서만 됩니다

OpenAI 규격에는 없는 기능이라 경로도 `/v1/` 아래가 아닙니다.

```
/api/voice-profiles
```

내 목소리나 정해둔 목소리를 등록해두고 `voice`로 지정합니다. 같은 화자로
**여러 편을 일관되게** 만들 수 있습니다.

> **⚠ 목소리는 개인정보입니다.**
> 다른 사람의 목소리를 복제하려면 그 사람의 동의가 필요합니다. 내부 자료라도
> 마찬가지이고, 대외로 나가는 콘텐츠라면 더 그렇습니다. **동의 없이 만들지
> 마세요.**

## 이미지 생성

```bash
curl -X POST http://localhost:27777/api/ai/v1/images/generations \
  -H "Authorization: Bearer $HT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<모델 이름>",
    "prompt": "a single glass capsule floating, centered, dark background"
  }'
```

응답에 이미지 주소가 담겨 옵니다. 그걸 내려받아 저장하는 단계가 따로 필요합니다.

### 배치로 만들 때

여러 장을 만들 때는 **프롬프트를 파일로 관리하세요.**

```json
[
  { "subject": "...", "composition": "centered", "mood": "solemn" },
  { "subject": "...", "composition": "low angle", "mood": "tense" }
]
```

이렇게 두면 얻는 게 셋입니다.

| 이유 | |
|---|---|
| 재현 | 같은 결과를 다시 만들 수 있음 |
| 수정 | 마음에 안 드는 것만 골라 다시 |
| 일관성 | 스타일 항목을 공통으로 적용 |

**프롬프트를 코드에 박아두면 이 셋을 다 잃습니다.**

### 이미지 편집·확대

| 경로 | 쓰임 |
|---|---|
| `/v1/images/inpainting` | 일부만 다시 그리기 |
| `/v1/images/upscale` | 해상도 올리기 |

**생성은 낮은 해상도로 여러 장, 고른 것만 확대**하는 순서가 시간과 비용에
유리합니다.

## 결과 파일을 어디에 두나

이게 실무에서 제일 자주 꼬이는 부분입니다.

```
작업폴더/
  prompts.json      ← 입력 (버전 관리)
  out/              ← 출력 (버전 관리 제외)
    img-001.png
    voice-001.wav
```

| 원칙 | 이유 |
|---|---|
| 입력과 출력을 폴더로 분리 | 다시 만들 때 지울 것이 명확 |
| 출력은 git에서 제외 | 이진 파일이 저장소를 불립니다 |
| 파일명에 순번·날짜 | 순서가 중요한 파이프라인에서 필수 |

## 시간이 오래 걸립니다

| 작업 | 감각 |
|---|---|
| 짧은 문장 음성 | 초 단위 |
| 긴 원고 음성 | 분 단위 |
| 이미지 한 장 | 초~분 |
| 이미지 수십 장 | **십 분 이상** |

그래서 이런 작업은 **[예약](/guide/ht-pipelines)으로 돌리고 결과만 확인**하는
편이 낫습니다. 화면 앞에서 기다릴 일이 아닙니다.

## 자주 하는 실수

### 실패한 항목을 처음부터 다시 만듭니다

50장 중 3장이 실패했는데 전체를 다시 돌립니다. **이미 있는 파일은 건너뛰도록**
만드세요. 파일명이 예측 가능해야 이게 됩니다.

### 프롬프트를 기록 안 합니다

마음에 드는 이미지가 나왔는데 어떤 프롬프트였는지 모릅니다. **입력 파일을 같이
남기세요.**

### 목소리 동의를 안 받습니다

앞에서 적었지만 다시 씁니다. **복제 목소리는 동의가 전제입니다.**

---

## 확인

**1. 긴 원고를 음성으로 만들 때 왜 나눠야 합니까?**

<details>
<summary>답</summary>

**한 번에 넣으면 오래 걸리고 중간에 실패하면 처음부터**이기 때문입니다. 문단별로
만들어 이어붙이면 실패한 부분만 다시 만들 수 있습니다.
</details>

**2. 이미지 프롬프트를 파일로 관리하면 무엇이 좋습니까?**

<details>
<summary>답</summary>

**재현·수정·일관성** 셋입니다. 같은 결과를 다시 만들 수 있고, 마음에 안 드는
것만 골라 다시 만들 수 있고, 스타일을 공통으로 적용할 수 있습니다.
</details>

**3. 복제 목소리를 쓸 때 반드시 확인할 것은?**

<details>
<summary>답</summary>

**목소리 주인의 동의**입니다. 목소리는 개인정보이고, 내부 자료라도 동의 없이
복제하면 안 됩니다.
</details>

---

이제 이것들을 자동으로 돌게 만듭니다 →
[예약으로 파이프라인 만들기](/guide/ht-pipelines)