apick-api 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 4.2.1
+
+- `youtubeSubtitle()` fails with guidance to use an original-language track when an auto-translated caption (`translated: true`) is refused; such calls are not charged. Examples now pick a manual or original-language track. YouTube requests interrupted by a server restart are retried automatically.
+- 자동 번역 자막(`translated: true`)을 받지 못하면 원어 자막을 쓰라는 안내와 함께 실패로 응답합니다(과금 없음). 예제는 수동·원어 자막을 고르도록 바꿨습니다. 서버 재시작으로 끊긴 유튜브 요청은 서버가 자동으로 다시 시도합니다.
+
 # 4.2.0
 
 - Add `amazonProduct`, `xProfile` and `xPost`, and collection jobs `createInstagramPostsJob`, `createInstagramCommentsJob`, `createTiktokSearchJob`, `createTiktokVideoJob`, `createTiktokCommentsJob`, `createAmazonReviewsJob` with `getScrapeJob` and `waitForScrapeJob`, all with typed results.

package/README.md

@@ -78,7 +78,7 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `youtubeMetadata(url)` | 유튜브 영상 정보 / YouTube video metadata | JSON |
 | `youtubeThumbnail(url)` | 유튜브 썸네일 / YouTube thumbnail | JPG |
 | `youtubeSubtitleList(url)` | 유튜브 자막 언어 목록 / YouTube subtitle languages | JSON |
-| `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드 / YouTube subtitles | VTT·SRT·TXT |
+| `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드(원어 자막 권장) / YouTube subtitles (prefer original-language tracks) | VTT·SRT·TXT |
 | `youtubeSearch(query, options)` | 유튜브 검색(정렬·필터) / YouTube search with sort and filters | JSON |
 | `youtubeChannel(channel, options)` | 유튜브 채널 정보·탭 목록 / YouTube channel and tab items | JSON |
 | `youtubePlaylist(url, options)` | 유튜브 재생목록 / YouTube playlist | JSON |

package/docs/guide.en.md

@@ -128,7 +128,9 @@ await screenshot.save('./example.jpeg');
 // Public YouTube videos: a video URL or the 11-character video ID
 const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
 const tracks = await client.youtubeSubtitleList(video.data.video_id);
-const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+// Auto-translated captions (translated=true) may be refused by YouTube, so pick a manual or original-language track.
+const track = tracks.data.subtitles[0] || tracks.data.automatic_captions.find(item => !item.translated);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, track.lang, { format: 'srt' });
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 

package/docs/guide.ko.md

@@ -128,7 +128,9 @@ await screenshot.save('./example.jpeg');
 // 유튜브 공개 영상: 영상 주소 또는 11자리 영상 ID
 const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
 const tracks = await client.youtubeSubtitleList(video.data.video_id);
-const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+// 자동 번역 자막(translated=true)은 유튜브 제한으로 받지 못할 수 있어 수동 자막이나 원어 자동 자막을 고른다.
+const track = tracks.data.subtitles[0] || tracks.data.automatic_captions.find(item => !item.translated);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, track.lang, { format: 'srt' });
 await subtitle.save('./' + subtitle.filename);
 await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/index.d.ts

@@ -455,6 +455,7 @@ export interface YoutubeMetadata {
 	age_limit: number | null; chapters: YoutubeChapter[]; thumbnail: string | null; thumbnails: YoutubeThumbnail[];
 	subtitle_languages: string[]; automatic_caption_count: number;
 }
+/** translated=true 인 자동 번역 자막은 유튜브 제한으로 받지 못할 수 있다. 수동 자막이나 원어 자동 자막을 권장한다. */
 export interface YoutubeSubtitleTrack { lang: string; name: string | null; auto: boolean; formats: string[]; translated?: boolean; }
 export interface YoutubeSubtitleList {
 	video_id: string; title: string | null; original_language: string | null;