La documentation développeur est publiée en anglais. La navigation latérale suit la langue choisie.

Référence de l'API

URL de base : https://api.subdownload.com · Auth : Authorization: Bearer sk_live_xxx

Endpoints

GET /v1/verify free

Vérifie qu'une clé API est valide. Renvoie les infos de token et d'utilisateur. Ne consomme pas de crédits.

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

Réponse 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

Récupère la transcription / sous-titres d'une vidéo YouTube. Accepte un ID vidéo ou toute URL YouTube valide (watch, youtu.be, shorts).

Paramètres

Nom	Type	Obligatoire	Description
`video_id`	string	REQUIS	ID vidéo de 11 caractères ou URL YouTube complète. Alias : `video_url`.
`lang`	string	optionnel	Codes de langue préférés, séparés par virgule (ex. `en,zh,ja`).

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

Réponse 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

Erreurs

400 video_id manquant · 404 pas de sous-titres · 402 crédits épuisés

GET /v1/youtube/search 1 credit

Recherche sur YouTube des vidéos ou chaînes correspondant à un mot-clé.

Paramètres

Nom	Type	Obligatoire	Description
`q`	string	REQUIS	Requête de recherche (1-200 caractères).
`type`	string	optionnel	`video` (défaut) ou `channel`.
`limit`	integer	optionnel	1-50 résultats (défaut 20).

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

Résout toute référence de chaîne (@handle, URL, ou ID UC…) en informations canoniques.

Paramètres

Nom	Type	Obligatoire	Description
`input`	string	REQUIS	@handle, URL de chaîne, URL vidéo ou ID UC…

GET /v1/youtube/channel/search 1 credit

Recherche dans les vidéos d'une chaîne spécifique.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	REQUIS	@handle, URL ou ID UC… (alias : `channel_id`).
`q`	string	REQUIS	Requête de recherche.
`limit`	integer	optionnel	1-50 (défaut 30).

GET /v1/youtube/channel/latest free

Récupère les ~15 vidéos les plus récentes d'une chaîne via RSS. Rapide et gratuit.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	REQUIS	@handle, URL ou ID UC… (alias : `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

Liste toutes les vidéos uploadées par une chaîne, paginé ~100 par page.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	première page	@handle, URL ou ID UC… (alias : `channel_id`).
`continuation`	string	pages suivantes	Token renvoyé par l'appel précédent.

Note : fournissez soit channel soit continuation, pas les deux.

GET /v1/youtube/playlist/videos 1 credit/page

Liste les vidéos d'une playlist YouTube avec pagination.

Paramètres

Nom	Type	Obligatoire	Description
`playlist`	string	première page	URL ou ID de playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	pages suivantes	Token de la réponse précédente.

Transcription IA (ASR)

Lancez Whisper sur des vidéos sans sous-titres. Asynchrone : POST crée une tâche, puis vous interrogez GET jusqu'à status=done. 5 crédits, facturés uniquement à la réussite — relancer l'ASR sur une vidéo déjà payée est gratuit.

POST /v1/youtube/asr 5 crédits à done

Démarre une transcription IA Whisper asynchrone. Renvoie task_id et des indices d'ETA pour cadencer le polling.

Corps (JSON)

Nom	Type	Obligatoire	Description
`video_url`	string	REQUIS	URL YouTube (watch / youtu.be / shorts / embed).
`lang`	string	optionnel	Indice de langue (`en`, `fr`…). Omettez pour détection auto.

Requête

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

Réponse 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

Respectez next_poll_after_seconds entre chaque poll. En cas de hit cache, status=done est retourné immédiatement avec les segments inclus.

GET /v1/youtube/asr/{task_id} gratuit

Interroge une tâche ASR. Gratuit — aucun crédit ni quota consommé. Seul le créateur peut lire.

Statuts : queued · downloading · transcribing · done · failed · cancelled. Les segments ne sont définitifs que lorsque status=done.

Library (espace utilisateur)

Stockage par utilisateur des transcriptions et résumés IA. Lectures gratuites ; écritures consomment une unité de quota token. Aucun crédit utilisateur facturé.

GET /v1/library gratuit

Liste les éléments que l'utilisateur a enregistrés dans sa Library (transcriptions + résumés).

Paramètres

Nom	Type	Obligatoire	Description
`favorite`	string	optionnel	`1` ou `true` pour ne renvoyer que les favoris.
`q`	string	optionnel	Recherche par sous-chaîne sur titre/auteur.
`tag`	string	optionnel	Filtre par tag.
`limit`	integer	optionnel	1–100 (par défaut 20).
`offset`	integer	optionnel	Décalage de pagination.

GET /v1/library/{id} gratuit

Récupère les métadonnées d'un élément Library. Utilisez has_asr / has_summary pour décider de l'endpoint de contenu à appeler ensuite.

GET /v1/library/{id}/transcript gratuit

Renvoie les segments ASR et le texte concaténé pour un élément Library. 404 si aucun ASR terminé n'existe pour la vidéo.

GET /v1/library/{id}/summary gratuit

Récupère le texte de résumé stocké. Utilisez ?locale= pour choisir parmi les locales stockées (par défaut Accept-Language puis en). 404 si aucun résumé n'existe pour ce (video_id, locale).

POST /v1/library gratuit (1 quota token)

kind=asr marque un transcript enregistré (segments déjà présents dans la table ASR). kind=summary téléverse un texte de résumé pré-généré dans la table summaries et marque has_summary=true. Upsert sur (video_id, locale).

Corps (JSON)

Nom	Type	Obligatoire	Description
`video_id`	string	REQUIS	ID de la vidéo YouTube.
`kind`	string	REQUIS	`asr` ou `summary`.
`title / author / thumbnail / video_url / language / tag`	string	optionnel	Métadonnées d'affichage / filtrage.
`locale`	string	mode summary	Locale du résumé (par défaut `Accept-Language` puis `en`).
`text`	string	si kind=summary	Texte du résumé à persister.
`model`	string	optionnel	Identifiant du LLM (ex : `claude-opus-4`).

DELETE /v1/library/{id} gratuit

Suppression logique d'un élément Library. Un nouveau POST /v1/library pour la même vidéo restaure la ligne au lieu de créer un doublon.

SDK officiels

Utilisez nos bibliothèques officielles pour une intégration rapide :

Langage	Dépôt
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Source complet : github.com/SubDownload/api-sdk

→ Pour la facturation, limites de débit et codes d'erreur, voir Support et facturation.

La documentation développeur est publiée en anglais. La navigation latérale suit la langue choisie.

Référence de l'API

URL de base : https://api.subdownload.com · Auth : Authorization: Bearer sk_live_xxx

Endpoints

GET /v1/verify free

Vérifie qu'une clé API est valide. Renvoie les infos de token et d'utilisateur. Ne consomme pas de crédits.

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

Réponse 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

Récupère la transcription / sous-titres d'une vidéo YouTube. Accepte un ID vidéo ou toute URL YouTube valide (watch, youtu.be, shorts).

Paramètres

Nom	Type	Obligatoire	Description
`video_id`	string	REQUIS	ID vidéo de 11 caractères ou URL YouTube complète. Alias : `video_url`.
`lang`	string	optionnel	Codes de langue préférés, séparés par virgule (ex. `en,zh,ja`).

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

Réponse 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

Erreurs

400 video_id manquant · 404 pas de sous-titres · 402 crédits épuisés

GET /v1/youtube/search 1 credit

Recherche sur YouTube des vidéos ou chaînes correspondant à un mot-clé.

Paramètres

Nom	Type	Obligatoire	Description
`q`	string	REQUIS	Requête de recherche (1-200 caractères).
`type`	string	optionnel	`video` (défaut) ou `channel`.
`limit`	integer	optionnel	1-50 résultats (défaut 20).

Requête

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

Résout toute référence de chaîne (@handle, URL, ou ID UC…) en informations canoniques.

Paramètres

Nom	Type	Obligatoire	Description
`input`	string	REQUIS	@handle, URL de chaîne, URL vidéo ou ID UC…

GET /v1/youtube/channel/search 1 credit

Recherche dans les vidéos d'une chaîne spécifique.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	REQUIS	@handle, URL ou ID UC… (alias : `channel_id`).
`q`	string	REQUIS	Requête de recherche.
`limit`	integer	optionnel	1-50 (défaut 30).

GET /v1/youtube/channel/latest free

Récupère les ~15 vidéos les plus récentes d'une chaîne via RSS. Rapide et gratuit.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	REQUIS	@handle, URL ou ID UC… (alias : `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

Liste toutes les vidéos uploadées par une chaîne, paginé ~100 par page.

Paramètres

Nom	Type	Obligatoire	Description
`channel`	string	première page	@handle, URL ou ID UC… (alias : `channel_id`).
`continuation`	string	pages suivantes	Token renvoyé par l'appel précédent.

Note : fournissez soit channel soit continuation, pas les deux.

GET /v1/youtube/playlist/videos 1 credit/page

Liste les vidéos d'une playlist YouTube avec pagination.

Paramètres

Nom	Type	Obligatoire	Description
`playlist`	string	première page	URL ou ID de playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	pages suivantes	Token de la réponse précédente.

Transcription IA (ASR)

POST /v1/youtube/asr 5 crédits à done

Démarre une transcription IA Whisper asynchrone. Renvoie task_id et des indices d'ETA pour cadencer le polling.

Corps (JSON)

Nom	Type	Obligatoire	Description
`video_url`	string	REQUIS	URL YouTube (watch / youtu.be / shorts / embed).
`lang`	string	optionnel	Indice de langue (`en`, `fr`…). Omettez pour détection auto.

Requête

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

Réponse 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

Respectez next_poll_after_seconds entre chaque poll. En cas de hit cache, status=done est retourné immédiatement avec les segments inclus.

GET /v1/youtube/asr/{task_id} gratuit

Interroge une tâche ASR. Gratuit — aucun crédit ni quota consommé. Seul le créateur peut lire.

Statuts : queued · downloading · transcribing · done · failed · cancelled. Les segments ne sont définitifs que lorsque status=done.

Library (espace utilisateur)

Stockage par utilisateur des transcriptions et résumés IA. Lectures gratuites ; écritures consomment une unité de quota token. Aucun crédit utilisateur facturé.

GET /v1/library gratuit

Liste les éléments que l'utilisateur a enregistrés dans sa Library (transcriptions + résumés).

Paramètres

Nom	Type	Obligatoire	Description
`favorite`	string	optionnel	`1` ou `true` pour ne renvoyer que les favoris.
`q`	string	optionnel	Recherche par sous-chaîne sur titre/auteur.
`tag`	string	optionnel	Filtre par tag.
`limit`	integer	optionnel	1–100 (par défaut 20).
`offset`	integer	optionnel	Décalage de pagination.

GET /v1/library/{id} gratuit

Récupère les métadonnées d'un élément Library. Utilisez has_asr / has_summary pour décider de l'endpoint de contenu à appeler ensuite.

GET /v1/library/{id}/transcript gratuit

Renvoie les segments ASR et le texte concaténé pour un élément Library. 404 si aucun ASR terminé n'existe pour la vidéo.

GET /v1/library/{id}/summary gratuit

POST /v1/library gratuit (1 quota token)

Corps (JSON)

Nom	Type	Obligatoire	Description
`video_id`	string	REQUIS	ID de la vidéo YouTube.
`kind`	string	REQUIS	`asr` ou `summary`.
`title / author / thumbnail / video_url / language / tag`	string	optionnel	Métadonnées d'affichage / filtrage.
`locale`	string	mode summary	Locale du résumé (par défaut `Accept-Language` puis `en`).
`text`	string	si kind=summary	Texte du résumé à persister.
`model`	string	optionnel	Identifiant du LLM (ex : `claude-opus-4`).

DELETE /v1/library/{id} gratuit

Suppression logique d'un élément Library. Un nouveau POST /v1/library pour la même vidéo restaure la ligne au lieu de créer un doublon.

SDK officiels

Utilisez nos bibliothèques officielles pour une intégration rapide :

Langage	Dépôt
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Source complet : github.com/SubDownload/api-sdk

→ Pour la facturation, limites de débit et codes d'erreur, voir Support et facturation.