Enhance public API docs

content/docs-ko/api/cookbook.md

@@ -0,0 +1,210 @@
+---
+title: API cookbook
+description: 인증, 작업, 생성, 업로드, Asset Library, Reference Analysis를 위한 Sume Public API 예시입니다.
+---
+
+이 cookbook은 자주 쓰는 Sume API 워크플로를 짧은 예시로 정리합니다. 정확한
+필드와 enum은 [API 레퍼런스](/ko/api/reference)와
+[`/api/openapi.json`](/api/openapi.json)을 사용하세요.
+
+## Setup
+
+```bash
+export SUME_API_KEY="sume_live_..."
+export SUME_API_BASE_URL="https://www.sume.so/api/v1"
+```
+
+키 확인:
+
+```bash
+curl "$SUME_API_BASE_URL/me" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+크레딧 확인:
+
+```bash
+curl "$SUME_API_BASE_URL/credits" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+## 비디오 작업 생성과 폴링
+
+작업 생성:
+
+```bash
+curl "$SUME_API_BASE_URL/videos/generations" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "A creator holds a moisturizer jar in soft morning light.",
+    "duration": 4,
+    "aspect_ratio": "9:16",
+    "resolution": "480p",
+    "generate_audio": false
+  }'
+```
+
+응답의 `job_id`를 저장합니다.
+
+상태 폴링:
+
+```bash
+curl "$SUME_API_BASE_URL/jobs/job_123" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+결과 가져오기:
+
+```bash
+curl "$SUME_API_BASE_URL/jobs/job_123/result" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+## Brand reference로 이미지 생성
+
+현재 Brand DNA 프로필 조회:
+
+```bash
+curl "$SUME_API_BASE_URL/brand/current" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+응답에 `images[].reference_url`이 있으면 이미지 생성 reference로 전달할 수
+있습니다.
+
+```bash
+curl "$SUME_API_BASE_URL/images/generations" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "Premium skincare product ad using the brand reference.",
+    "aspect_ratio": "1:1",
+    "image_count": 1,
+    "reference_image_urls": [
+      "https://media.sume.so/example-reference.jpg"
+    ]
+  }'
+```
+
+워크스페이스에 반환된 reference URL만 사용하고, private 또는 signed URL을
+로그에 남기지 마세요.
+
+## Asset Library 비디오 업로드
+
+업로드 대상 요청:
+
+```bash
+curl "$SUME_API_BASE_URL/uploads/presign" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "purpose": "asset_library_video",
+    "file_name": "source.mp4",
+    "content_type": "video/mp4",
+    "size_bytes": 12000000
+  }'
+```
+
+반환된 `upload_url`과 `required_headers`로 파일 바이트를 업로드합니다. Storage
+PUT 요청에는 Sume API `Authorization` 헤더를 넣지 마세요.
+
+업로드 finalize:
+
+```bash
+curl "$SUME_API_BASE_URL/assets" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "object_key": "uploads/...",
+    "file_name": "source.mp4",
+    "content_type": "video/mp4",
+    "size_bytes": 12000000
+  }'
+```
+
+## Asset Library 장면 검색
+
+```bash
+curl "$SUME_API_BASE_URL/assets?q=product%20demo%20hook&limit=5&sort=relevance" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+하나의 장면 조회:
+
+```bash
+curl "$SUME_API_BASE_URL/assets/asset_123" \
+  -H "Authorization: Bearer $SUME_API_KEY"
+```
+
+Scene asset에는 scene-level `media_url`, `thumbnail_url`, `source_video`,
+`scene` metadata, search context가 포함될 수 있습니다.
+
+## Face Swap source video 준비
+
+Face Swap은 `face_swap_source_video` purpose로 업로드한 Sume media URL이
+필요합니다.
+
+```bash
+curl "$SUME_API_BASE_URL/uploads/presign" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "purpose": "face_swap_source_video",
+    "file_name": "source.mp4",
+    "content_type": "video/mp4",
+    "size_bytes": 12000000
+  }'
+```
+
+바이트 업로드 후 Face Swap 작업 생성:
+
+```bash
+curl "$SUME_API_BASE_URL/face-swap" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_video_url": "https://media.sume.so/example-source.mp4",
+    "avatar_ids": ["avatar_123"],
+    "duration_seconds": 6,
+    "aspect_ratio": "9:16"
+  }'
+```
+
+반환된 각 job id를 `GET /jobs/{jobId}`로 폴링합니다.
+
+## Reference Analysis
+
+Reference Analysis는 공개 TikTok 또는 Instagram Reel URL을 받습니다.
+
+```bash
+curl "$SUME_API_BASE_URL/reference-analysis" \
+  -H "Authorization: Bearer $SUME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://www.tiktok.com/@example/video/123",
+    "locale": "ko"
+  }'
+```
+
+응답에는 `required_credits`와 `job_id`가 포함됩니다. Jobs endpoint로 폴링하고
+최종 결과를 가져오세요.
+
+## 실패 처리
+
+API 요청 실패 시 `request_id`를 보관합니다.
+
+```json
+{
+  "error": {
+    "code": "invalid_request",
+    "message": "A human-readable error message.",
+    "details": {}
+  },
+  "request_id": "req_123"
+}
+```
+
+Job 실패 시 job id, status, 정리된 error code/message만 기록하세요. API 키,
+signed URL, storage object key, provider payload, private media URL, 사용자
+이메일, workspace/user id는 로그에 남기지 마세요.