# API 참조 문서

이 참조 문서는 개발자와 자동화 에이전트가 Weydub API 엔드포인트, 액세스 확인 사항, 요청 구조, 비동기 동작, 과금/보존 규칙 및 문제 해결 단서를 한 곳에서 간편하게 찾을 수 있도록 합니다.

## 요청 기본 사항

| 항목 | 값 |
| --- | --- |
| 기본 URL | `https://api.zhaoli.com` |
| 프로토콜 | HTTPS |
| 메서드 | 문서화된 API 호출에는 `POST` 사용 |
| 인코딩 | UTF-8 |
| 콘텐츠 유형 | `application/json` |
| 인증 | 명시적으로 서명이 필요 없다고 표시된 엔드포인트를 제외하고 `AppKey` 및 `AppSign` 헤더 사용 |

일부 레거시 인프라 이름이 공개 데모 자산이나 이전 계정 경로에 여전히 표시될 수 있습니다. 이 Weydub API 문서를 현재 제품에 적용되는 계약으로 간주하세요.

## 호출 전 확인 사항

| 확인 항목 | 확인할 내용 | 중요한 이유 |
| --- | --- | --- |
| API 액세스 | 로그인한 Weydub 계정에서 API 액세스를 무료로 활성화할 수 있습니다. 필요한 경우 워크플로별 사용 권한을 확인하세요. | 일부 작업 계열, 특히 이미지 번역과 감정 표현이 풍부한 더빙은 계정별로 프로비저닝될 수 있습니다. |
| 자격 증명 | `AppKey`와 `AppSecret`을 보유하고 있으며 백엔드 비밀 정보로 저장되어 있습니다. | `AppSecret`은 프런트엔드 코드, 공개 저장소, 로그, 스크린샷 또는 프롬프트에 절대 표시되어서는 안 됩니다. |
| 미디어 URL | 처리 기간 동안 원본 파일에 공개적으로 접근할 수 있고 URL이 안정적으로 유지됩니다. | Weydub 작업자는 처리 전에 원본 미디어를 다운로드해야 합니다. |
| 콜백 URL | 프로덕션 콜백은 영속적 저장이 완료된 후에만 HTTP 200과 비어 있지 않은 본문을 반환합니다. | 비동기 작업은 원래 요청이 반환된 후에 완료될 수 있습니다. |
| 결과 저장 | 서비스에서 작업 ID, 태스크 ID, 상태, 결과 URL 및 오류를 저장합니다. | 생성된 자산에는 보존 정책이 적용될 수 있으므로 지속적으로 보관할 참조 정보를 신속히 복사하세요. |

## 인증

대부분의 요청은 다음 헤더를 사용합니다:

```text
Content-Type: application/json
AppKey: $WEYDUB_APP_KEY
AppSign: md5(md5(request_body) + $WEYDUB_APP_SECRET)
```

전송할 정확한 축약형 JSON 본문에 서명하세요. 서명 실패를 디버깅하기 전에 [인증 및 서명](./auth-and-signing.md)을 읽어보세요.

서명이 필요 없는 예외:

```text
POST /v-w-c/enum/query2
```

열거형 조회 엔드포인트는 동적 언어/상태 목록에 사용되며 서명이 필요하지 않습니다.

## 엔드포인트 색인

| 메서드 | 경로 | 계열 | 용도 | 액세스 참고 사항 |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | 비디오 | 자막/텍스트 제거, 비디오 번역, OCR 자막 추출, ASR 추출 및 자막 렌더링을 포함한 대부분의 비디오 작업을 생성합니다. | 핵심 API 액세스가 필요합니다. |
| `POST` | `/v-w-c/gateway/ve/work/status` | 비디오 | 작업 ID로 비디오 작업 상태 및 결과 필드를 조회합니다. | 작업 생성 후 또는 콜백 대체 수단으로 사용합니다. |
| `POST` | `/v-w-c/gateway/ve/work/list` | 비디오 | 과거 비디오 작업을 조회합니다. | 내부 대시보드 및 정합성 확인에 유용합니다. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | 비디오 | 조정된 마스크를 사용하여 텍스트 제거/인페인팅을 다시 실행합니다. | 기존 작업/태스크 컨텍스트가 필요합니다. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | 비디오 | 조정된 자막, 타이밍 또는 음성 설정으로 번역/더빙을 다시 실행합니다. | 기존 번역 작업 컨텍스트가 필요합니다. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | 비디오 | 감정 표현이 풍부한 음성 복제 및 더빙 작업을 생성합니다. | 프로덕션 트래픽을 연동하기 전에 계정 사용 권한을 확인하세요. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | 이미지 | 이미지 텍스트 제거 또는 이미지 번역 작업을 생성합니다. | 무료 API 액세스를 활성화한 후에도 이미지 워크플로 사용 권한이 필요할 수 있습니다. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | 이미지 | 결과 텍스트/스타일 메타데이터를 편집한 후 이미지 작업을 재생성합니다. | 기존 이미지 작업 ID와 결과 JSON이 필요합니다. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | 이미지 레거시/웹 | 이전 계정 또는 웹 흐름에서 단일 이미지 작업을 생성합니다. | 해당 계정에서 사용 가능함을 확인한 경우에만 사용하세요. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | 이미지 레거시/웹 | 이전 계정 또는 웹 흐름에서 이미지 일괄 작업을 생성합니다. | 일괄 처리 한도와 콜백 정책을 확인하세요. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | 이미지 레거시/웹 | 이전 계정 또는 웹 흐름에서 이미지 작업 하나를 조회합니다. | 출력을 읽기 전에 종료 상태가 될 때까지 폴링하세요. |
| `POST` | `/v-w-c/enum/query2` | 유틸리티 | 상태 및 언어 목록과 같은 동적 열거형을 조회합니다. | 서명이 필요하지 않습니다. |

## 비디오 작업 생성

```text
POST /v-w-c/gateway/ve/work/free
```

이 엔드포인트를 사용하는 일반적인 워크플로:

| 워크플로 | 필수 신호 | 시작 페이지 |
| --- | --- | --- |
| 자막/텍스트 제거 | `needChineseOcclude: 1`, `2` 또는 `3`; `extraOptions.extra_inpaint_config`를 통한 Advanced Lite/Pro | [비디오 자막 및 텍스트 제거](./video-subtitle-removal.md) |
| 비디오 번역/더빙 | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [비디오 번역](./video-translation.md) |
| 화면 내 텍스트 번역 | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [비디오 번역](./video-translation.md) |
| OCR 자막 추출 | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [자막 추출](./subtitle-extraction.md) |
| ASR 자막 추출 | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [자막 추출](./subtitle-extraction.md) |

최소 요청:

```json
{
  "urls": ["https://example.com/demo.mp4"],
  "needChineseOcclude": 1,
  "videoInpaintLang": "all",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

일반적인 생성 응답 필드:

| 필드 | 의미 |
| --- | --- |
| `idProject` | 배치/프로젝트 ID. |
| `dataList[].id` | 상태 폴링 및 콜백 일치 확인을 위한 작업 ID. |
| `dataList[].url` | 처리 대상으로 수락된 원본 URL. |

## 비디오 상태 조회

```text
POST /v-w-c/gateway/ve/work/status
```

```json
{
  "idWorks": [488026661]
}
```

상태 값:

| `processStatus` | 의미 | 클라이언트 동작 |
| --- | --- | --- |
| `< 1` | 처리 중. | 나중에 폴링하거나 콜백을 기다리세요. |
| `1` | 성공. | 결과 URL을 확인하고 영구 저장하세요. |
| `> 1` | 실패. | `errorDetail`을 표시하세요. 실패한 작업은 크레딧을 전혀 차감하지 않습니다. |

성공한 비디오 작업에는 `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` 및 작업 메타데이터가 포함될 수 있습니다.

## 이미지 작업

현재 공개 생성 엔드포인트:

```text
POST /v-w-c/gateway/ve/image/translate
```

재실행 엔드포인트:

```text
POST /v-w-c/gateway/ve/image/translate/redo
```

이미지 번역 요청:

```json
{
  "srcLang": "en",
  "tgtLang": "es",
  "translateOn": 1,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/product.png\",\"fileName\":\"product.png\",\"id\":12345,\"materialName\":\"product.png\"}",
  "app": "WD"
}
```

이미지 텍스트 제거 요청:

```json
{
  "srcLang": "en",
  "tgtLang": "en",
  "translateOn": 0,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/banner.png\",\"fileName\":\"banner.png\",\"id\":12346,\"materialName\":\"banner.png\"}",
  "app": "WD"
}
```

이미지 작업을 구현하기 전에 [이미지 번역](./image-translation.md)을 읽어보세요. `downloadInfo`, `downloadInfos` 및 재실행 `result`은 문서화된 문자열 형식을 유지해야 합니다.

## 열거형 조회

```text
POST /v-w-c/enum/query2
```

이 엔드포인트에는 `AppSign`이 필요하지 않습니다.

```json
{
  "text": "Lang"
}
```

일반적인 열거형 이름:

| `text` | 용도 |
| --- | --- |
| `ProcessStatus` | 비디오 작업 상태 코드. |
| `ImageTaskStatus` | 이미지 작업 상태 코드. |
| `sourceLang` | 비디오 번역 원본 언어 목록. |
| `Lang` | 비디오 번역 대상 언어 목록. |
| `musicRegion` | 지원되는 경우 사용할 스마트 음악 지역 목록. |

## 과금, 한도 및 보존

| 주제 | 규칙 |
| --- | --- |
| 비디오 길이 | 현재 최대 허용 한도는 비디오 파일당 15분입니다. 길이 반올림 문제를 방지하려면 더 긴 미디어를 15분 미만의 구간(예: 14:59)으로 분할하세요. |
| 비디오 크기 | 현재 최대 허용 한도는 비디오 파일당 1000MB입니다. 크기 제한을 초과하는 파일은 제출하기 전에 압축하세요. |
| 이미지 한도 | 최대 `2000*2000 px`, 최대 `50 MB`, 지원 형식은 `png`, `jpeg`, `jpg`, `bmp`, `webp`이며 이미지 URL에는 중국어 문자가 포함되어서는 안 됩니다. |
| 과금 단위 | 비디오 워크플로는 30초 단위로 과금됩니다. 30초 미만의 비디오는 30초로 계산됩니다. |
| 결합 서비스 | 텍스트 제거와 음성 번역 같은 서비스를 결합하면 비용이 누적될 수 있습니다. |
| 실패한 작업 | 최종 실패로 확정된 작업(`processStatus > 1`)에는 크레딧이 차감되지 않습니다. |
| 보존 | API로 생성된 데이터에는 Weydub 웹 보존 규칙이 적용됩니다. 기본적으로 최근 30일간의 소스 파일과 렌더링된 출력물이 보존됩니다. 콜백 후 중요한 자산을 다운로드하여 저장하세요. |
| CRF | 기본 비디오 CRF는 `17`이며, 대부분의 배포 용도에서 육안상 무손실입니다. `15` 또는 `16`와 같은 더 낮은 값은 `extraOptions.write_options`을 통해 사용할 수 있으며, 대역폭 또는 저장 공간 요금이 추가될 수 있습니다. |

## 콜백 요약

지원되는 경우 생성 요청에 `callback` URL을 전달하세요. Weydub는 폴링 응답에 사용되는 외부 `code` / `msg` / `body` 래퍼 없이 완료된 작업 항목을 서버로 직접 전송합니다.

콜백 처리 규칙:

- 원본 콜백 요청 본문과 `AppSecret`을 사용하여 `Callback-Sign`을 검증합니다.
- 영구 저장에 성공한 후에만 HTTP 200과 비어 있지 않은 본문을 함께 반환합니다.
- 작업/태스크 ID를 기준으로 핸들러가 멱등성을 갖도록 구현합니다.
- 최근 24시간 이내에 생성된 태스크의 콜백이 실패하면 약 30분마다 재시도됩니다.
- 재실행으로 비디오 또는 이미지 콘텐츠가 변경되면 출력 URL이 변경될 수 있으므로 최신 결과 URL을 저장합니다.

콜백에 대한 자세한 내용은 [비동기 태스크 모델](./async-task-model.md)을 참조하세요.

## 문제 해결

| 증상 | 추정 원인 | 확인 사항 |
| --- | --- | --- |
| 서명 오류 | 서명 후 본문 바이트가 변경되었거나, 보기 좋게 서식이 지정된 JSON에 서명했지만 축약형 JSON을 전송했습니다. | 기밀이 아닌 본문 해시를 로그에 기록하고 서명 및 전송 코드 경로를 비교합니다. |
| 태스크는 생성되었지만 결과가 없음 | 비동기 처리가 아직 실행 중입니다. | `/v-w-c/gateway/ve/work/status`을 폴링하거나 콜백을 기다립니다. |
| 출력 URL 누락 | 워크플로 모드가 잘못되었거나 태스크가 종료 상태가 아닙니다. | `processStatus === 1`을 확인하고 워크플로별 출력 필드를 검토합니다. |
| 앱에 콜백이 반영되지 않음 | 핸들러가 영구 저장 전에 응답을 반환했거나, 서명 검증에 실패했거나, 작업 ID가 일치하지 않았습니다. | 원본 콜백 페이로드를 저장하고 `Callback-Sign`을 비교하며 업데이트가 멱등성을 갖도록 구현합니다. |
| 엔드포인트를 사용할 수 없음 | 계정 사용 권한이 활성화되지 않았습니다. | 해당 태스크 제품군에 대한 API 액세스를 확인합니다. |
| 비디오 하드 제한 오류 | 비디오가 15분보다 길거나 1000MB보다 큽니다. | 제출하기 전에 분할하거나 압축합니다. |
| 이미지 하드 제한 오류 | 이미지가 `2000*2000 px`을 초과하거나, `50 MB`을 초과하거나, 지원되지 않는 형식이거나, URL에 중국어 문자가 포함되어 있습니다. | 크기를 조정하고 다시 압축한 후 URL의 이름을 변경하거나 인코딩하고 다시 시도합니다. |

## 에이전트 계약

자동화 에이전트는 다음을 수행해야 합니다:

- [llms.txt](./llms.txt) 및 [Weydub API 스킬](./weydub-api-skill.md)을 불러옵니다.
- 고객 미디어를 사용하기 전에 [데모 시나리오](./demo-scenarios.md)를 사용합니다.
- 자격 증명을 환경 변수 또는 시크릿 관리 도구에 보관합니다.
- 사용자에게 성공을 보고하기 전에 ID를 영속적으로 저장합니다.
- 작업을 `submitted -> processing -> succeeded | failed | timed_out`로 모델링합니다.
- `AppSecret`을 절대 노출해서는 안 되며, 활성화된 엔드포인트를 임의로 만들어 내서도 안 됩니다.