La documentación para desarrolladores se publica en inglés. La navegación lateral sigue el idioma seleccionado.

Referencia de la API

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

Endpoints

GET /v1/verify free

Verifica que una clave API es válida. Devuelve info de token y usuario. No consume créditos.

Petición

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

Respuesta 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

Obtiene la transcripción / subtítulos de un vídeo de YouTube. Acepta un ID de vídeo o cualquier URL válida (watch, youtu.be, shorts).

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`video_id`	string	REQUERIDO	ID de vídeo de 11 caracteres o URL completa. Alias: `video_url`.
`lang`	string	opcional	Códigos de idioma preferidos, separados por coma (p. ej. `en,zh,ja`).

Petición

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

Respuesta 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
}

Errores

400 falta video_id · 404 sin subtítulos · 402 créditos agotados

GET /v1/youtube/search 1 credit

Busca en YouTube vídeos o canales que coincidan con una palabra clave.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`q`	string	REQUERIDO	Consulta de búsqueda (1-200 caracteres).
`type`	string	opcional	`video` (por defecto) o `channel`.
`limit`	integer	opcional	1-50 resultados (por defecto 20).

Petición

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

Resuelve cualquier referencia de canal (@handle, URL o ID UC…) a info canónica.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`input`	string	REQUERIDO	@handle, URL de canal, URL de vídeo o ID UC…

GET /v1/youtube/channel/search 1 credit

Busca dentro de los vídeos de un canal concreto.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	REQUERIDO	@handle, URL o ID UC… (alias: `channel_id`).
`q`	string	REQUERIDO	Consulta de búsqueda.
`limit`	integer	opcional	1-50 (por defecto 30).

GET /v1/youtube/channel/latest free

Recupera los ~15 vídeos más recientes de un canal vía RSS. Rápido y gratis.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	REQUERIDO	@handle, URL o ID UC… (alias: `channel_id`).

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

Lista todos los vídeos subidos por un canal, paginado ~100 por página.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	primera página	@handle, URL o ID UC… (alias: `channel_id`).
`continuation`	string	siguientes	Token devuelto por la llamada anterior.

Nota: proporciona channel o continuation, no ambos.

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

Lista los vídeos de una playlist de YouTube con paginación.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`playlist`	string	primera página	URL o ID de playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	siguientes	Token de la respuesta anterior.

Transcripción IA (ASR)

Ejecuta Whisper en vídeos sin subtítulos. Asíncrono: POST crea una tarea y luego consultas GET hasta status=done. 5 créditos, cobrados solo al completar con éxito — volver a ejecutar ASR sobre un vídeo ya pagado es gratis.

POST /v1/youtube/asr 5 créditos al done

Inicia una transcripción IA Whisper asíncrona. Devuelve task_id y pistas de ETA para cadenciar el polling.

Cuerpo (JSON)

Nombre	Tipo	Obligatorio	Descripción
`video_url`	string	REQUERIDO	URL de YouTube (watch / youtu.be / shorts / embed).
`lang`	string	opcional	Pista de idioma (`en`, `es`…). Omitir para autodetección.

Solicitud

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

Respuesta 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..."
}

Respeta next_poll_after_seconds entre polls. Si hay acierto de caché, devuelve status=done inmediatamente con los segments en línea.

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

Consulta una tarea ASR. Gratis — sin créditos ni cuota de token. Solo el creador puede leer.

Estados: queued · downloading · transcribing · done · failed · cancelled. Los segments solo son finales en status=done.

Library (biblioteca de usuario)

Almacenamiento por usuario de transcripciones y resúmenes IA guardados. Lecturas gratis; escrituras consumen una unidad de cuota de token. Sin créditos de usuario.

GET /v1/library gratis

Lista los elementos que el usuario ha guardado en su Library (transcripciones + resúmenes).

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`favorite`	string	opcional	`1` o `true` para devolver solo favoritos.
`q`	string	opcional	Coincidencia parcial en título/autor.
`tag`	string	opcional	Filtro por tag.
`limit`	integer	opcional	1–100 (por defecto 20).
`offset`	integer	opcional	Offset de paginación.

GET /v1/library/{id} gratis

Obtiene los metadatos de un elemento Library. Usa has_asr / has_summary para decidir qué endpoint de contenido llamar después.

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

Devuelve los segments ASR y el texto concatenado. 404 si no existe un ASR completado.

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

Devuelve el texto del resumen almacenado. Usa ?locale= para elegir entre locales guardados (por defecto Accept-Language y luego en). 404 si no existe resumen para (video_id, locale).

POST /v1/library gratis (1 cuota de token)

kind=asr marca que hay transcripción guardada (los segments ya están en la tabla ASR). kind=summary sube un texto de resumen pre-generado a la tabla summaries y marca has_summary=true. Upsert por (video_id, locale).

Cuerpo (JSON)

Nombre	Tipo	Obligatorio	Descripción
`video_id`	string	REQUERIDO	ID del vídeo de YouTube.
`kind`	string	REQUERIDO	`asr` o `summary`.
`title / author / thumbnail / video_url / language / tag`	string	opcional	Metadatos de visualización / filtrado.
`locale`	string	modo summary	Locale del resumen (por defecto `Accept-Language` luego `en`).
`text`	string	si kind=summary	Texto del resumen a persistir.
`model`	string	opcional	Identificador del LLM (p. ej. `claude-opus-4`).

DELETE /v1/library/{id} gratis

Soft-delete de un elemento Library. Un nuevo POST /v1/library sobre el mismo vídeo restaura la fila en lugar de crear un duplicado.

SDK oficiales

Usa nuestras bibliotecas oficiales para integrar la API rápido:

Lenguaje	Repositorio
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Código fuente completo: github.com/SubDownload/api-sdk

→ Para facturación, límites de tasa y códigos de error ver Soporte y facturación.

La documentación para desarrolladores se publica en inglés. La navegación lateral sigue el idioma seleccionado.

Referencia de la API

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

Endpoints

GET /v1/verify free

Verifica que una clave API es válida. Devuelve info de token y usuario. No consume créditos.

Petición

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

Respuesta 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

Obtiene la transcripción / subtítulos de un vídeo de YouTube. Acepta un ID de vídeo o cualquier URL válida (watch, youtu.be, shorts).

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`video_id`	string	REQUERIDO	ID de vídeo de 11 caracteres o URL completa. Alias: `video_url`.
`lang`	string	opcional	Códigos de idioma preferidos, separados por coma (p. ej. `en,zh,ja`).

Petición

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

Respuesta 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
}

Errores

400 falta video_id · 404 sin subtítulos · 402 créditos agotados

GET /v1/youtube/search 1 credit

Busca en YouTube vídeos o canales que coincidan con una palabra clave.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`q`	string	REQUERIDO	Consulta de búsqueda (1-200 caracteres).
`type`	string	opcional	`video` (por defecto) o `channel`.
`limit`	integer	opcional	1-50 resultados (por defecto 20).

Petición

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

Resuelve cualquier referencia de canal (@handle, URL o ID UC…) a info canónica.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`input`	string	REQUERIDO	@handle, URL de canal, URL de vídeo o ID UC…

GET /v1/youtube/channel/search 1 credit

Busca dentro de los vídeos de un canal concreto.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	REQUERIDO	@handle, URL o ID UC… (alias: `channel_id`).
`q`	string	REQUERIDO	Consulta de búsqueda.
`limit`	integer	opcional	1-50 (por defecto 30).

GET /v1/youtube/channel/latest free

Recupera los ~15 vídeos más recientes de un canal vía RSS. Rápido y gratis.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	REQUERIDO	@handle, URL o ID UC… (alias: `channel_id`).

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

Lista todos los vídeos subidos por un canal, paginado ~100 por página.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`channel`	string	primera página	@handle, URL o ID UC… (alias: `channel_id`).
`continuation`	string	siguientes	Token devuelto por la llamada anterior.

Nota: proporciona channel o continuation, no ambos.

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

Lista los vídeos de una playlist de YouTube con paginación.

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`playlist`	string	primera página	URL o ID de playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	siguientes	Token de la respuesta anterior.

Transcripción IA (ASR)

POST /v1/youtube/asr 5 créditos al done

Inicia una transcripción IA Whisper asíncrona. Devuelve task_id y pistas de ETA para cadenciar el polling.

Cuerpo (JSON)

Nombre	Tipo	Obligatorio	Descripción
`video_url`	string	REQUERIDO	URL de YouTube (watch / youtu.be / shorts / embed).
`lang`	string	opcional	Pista de idioma (`en`, `es`…). Omitir para autodetección.

Solicitud

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

Respuesta 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..."
}

Respeta next_poll_after_seconds entre polls. Si hay acierto de caché, devuelve status=done inmediatamente con los segments en línea.

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

Consulta una tarea ASR. Gratis — sin créditos ni cuota de token. Solo el creador puede leer.

Estados: queued · downloading · transcribing · done · failed · cancelled. Los segments solo son finales en status=done.

Library (biblioteca de usuario)

Almacenamiento por usuario de transcripciones y resúmenes IA guardados. Lecturas gratis; escrituras consumen una unidad de cuota de token. Sin créditos de usuario.

GET /v1/library gratis

Lista los elementos que el usuario ha guardado en su Library (transcripciones + resúmenes).

Parámetros

Nombre	Tipo	Obligatorio	Descripción
`favorite`	string	opcional	`1` o `true` para devolver solo favoritos.
`q`	string	opcional	Coincidencia parcial en título/autor.
`tag`	string	opcional	Filtro por tag.
`limit`	integer	opcional	1–100 (por defecto 20).
`offset`	integer	opcional	Offset de paginación.

GET /v1/library/{id} gratis

Obtiene los metadatos de un elemento Library. Usa has_asr / has_summary para decidir qué endpoint de contenido llamar después.

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

Devuelve los segments ASR y el texto concatenado. 404 si no existe un ASR completado.

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

Devuelve el texto del resumen almacenado. Usa ?locale= para elegir entre locales guardados (por defecto Accept-Language y luego en). 404 si no existe resumen para (video_id, locale).

POST /v1/library gratis (1 cuota de token)

Cuerpo (JSON)

Nombre	Tipo	Obligatorio	Descripción
`video_id`	string	REQUERIDO	ID del vídeo de YouTube.
`kind`	string	REQUERIDO	`asr` o `summary`.
`title / author / thumbnail / video_url / language / tag`	string	opcional	Metadatos de visualización / filtrado.
`locale`	string	modo summary	Locale del resumen (por defecto `Accept-Language` luego `en`).
`text`	string	si kind=summary	Texto del resumen a persistir.
`model`	string	opcional	Identificador del LLM (p. ej. `claude-opus-4`).

DELETE /v1/library/{id} gratis

Soft-delete de un elemento Library. Un nuevo POST /v1/library sobre el mismo vídeo restaura la fila en lugar de crear un duplicado.

SDK oficiales

Usa nuestras bibliotecas oficiales para integrar la API rápido:

Lenguaje	Repositorio
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Código fuente completo: github.com/SubDownload/api-sdk

→ Para facturación, límites de tasa y códigos de error ver Soporte y facturación.