A documentação para desenvolvedores é publicada em inglês. A navegação lateral segue o idioma escolhido.

Referência da API

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

Endpoints

GET /v1/verify free

Verifica se uma API Key é válida. Retorna informações de token e usuário. Não consome créditos.

Requisição

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

Resposta 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

Obtém a transcrição / legendas de um vídeo do YouTube. Aceita ID de vídeo ou qualquer URL YouTube válida (watch, youtu.be, shorts).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`video_id`	string	OBRIGATÓRIO	ID de vídeo de 11 caracteres ou URL completa do YouTube. Alias: `video_url`.
`lang`	string	opcional	Códigos de idioma preferidos, separados por vírgula (ex.: `en,zh,ja`).

Requisição

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

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

Erros

400 video_id faltando · 404 sem legendas · 402 créditos esgotados

GET /v1/youtube/search 1 credit

Busca no YouTube vídeos ou canais que correspondem a uma palavra-chave.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`q`	string	OBRIGATÓRIO	Consulta de busca (1-200 caracteres).
`type`	string	opcional	`video` (padrão) ou `channel`.
`limit`	integer	opcional	1-50 resultados (padrão 20).

Requisição

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

Resolve qualquer referência de canal (@handle, URL ou ID UC…) para info canônica do canal.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`input`	string	OBRIGATÓRIO	@handle, URL do canal, URL do vídeo ou ID UC…

GET /v1/youtube/channel/search 1 credit

Busca dentro dos vídeos de um canal específico.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	OBRIGATÓRIO	@handle, URL ou ID UC… (alias: `channel_id`).
`q`	string	OBRIGATÓRIO	Consulta de busca.
`limit`	integer	opcional	1-50 (padrão 30).

GET /v1/youtube/channel/latest free

Busca os ~15 vídeos mais recentes de um canal via RSS. Rápido e grátis.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	OBRIGATÓRIO	@handle, URL ou ID UC… (alias: `channel_id`).

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

Lista todos os vídeos enviados por um canal, paginado ~100 por página.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	primeira pág.	@handle, URL ou ID UC… (alias: `channel_id`).
`continuation`	string	próx. págs.	Token retornado pela chamada anterior.

Nota: forneça channel OU continuation, não ambos.

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

Lista vídeos em uma playlist do YouTube com paginação.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`playlist`	string	primeira pág.	URL ou ID da playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	próx. págs.	Token da resposta anterior.

Transcrição por IA (ASR)

Execute o Whisper em vídeos sem legendas. Assíncrono: POST cria uma tarefa e você consulta com GET até status=done. 5 créditos, cobrados apenas no sucesso — rodar ASR de novo no mesmo vídeo é grátis.

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

Inicia uma transcrição AI Whisper assíncrona. Retorna task_id e dicas de ETA para cadenciar o polling.

Corpo (JSON)

Nome	Tipo	Obrigatório	Descrição
`video_url`	string	OBRIGATÓRIO	URL do YouTube (watch / youtu.be / shorts / embed).
`lang`	string	opcional	Dica de idioma (`en`, `pt`…). Omita para detecção automática.

Requisição

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

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

Respeite next_poll_after_seconds entre polls. Com cache hit, status=done volta imediatamente com os segments inline.

GET /v1/youtube/asr/{task_id} grátis

Consulta uma tarefa ASR. Grátis — sem créditos e sem cota de token. Apenas o criador pode ler.

Status: queued · downloading · transcribing · done · failed · cancelled. Os segments só são finais em status=done.

Library (biblioteca do usuário)

Armazenamento por usuário para transcrições salvas e resumos de IA. Leituras grátis; escritas consomem uma unidade de cota de token. Sem créditos de usuário.

GET /v1/library grátis

Lista itens que o usuário salvou na sua Library (transcrições + resumos).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`favorite`	string	opcional	`1` ou `true` para retornar só favoritos.
`q`	string	opcional	Correspondência parcial em título/autor.
`tag`	string	opcional	Filtro por tag.
`limit`	integer	opcional	1–100 (padrão 20).
`offset`	integer	opcional	Offset de paginação.

GET /v1/library/{id} grátis

Obtém os metadados de um item Library. Use has_asr / has_summary para decidir qual endpoint de conteúdo chamar em seguida.

GET /v1/library/{id}/transcript grátis

Retorna os segments ASR e o texto concatenado. 404 se não houver ASR concluído.

GET /v1/library/{id}/summary grátis

Retorna o texto do resumo armazenado. Use ?locale= para escolher entre locales salvos (padrão Accept-Language, depois en). 404 quando não há resumo para (video_id, locale).

POST /v1/library grátis (1 cota de token)

kind=asr sinaliza transcrição salva (segments já na tabela ASR). kind=summary envia o texto do resumo pré-gerado para a tabela summaries e marca has_summary=true. Upsert em (video_id, locale).

Corpo (JSON)

Nome	Tipo	Obrigatório	Descrição
`video_id`	string	OBRIGATÓRIO	ID do vídeo do YouTube.
`kind`	string	OBRIGATÓRIO	`asr` ou `summary`.
`title / author / thumbnail / video_url / language / tag`	string	opcional	Metadados para exibição / filtragem.
`locale`	string	modo summary	Locale do resumo (padrão `Accept-Language` depois `en`).
`text`	string	se kind=summary	Texto do resumo a persistir.
`model`	string	opcional	Identificador do LLM (ex.: `claude-opus-4`).

DELETE /v1/library/{id} grátis

Soft-delete de um item Library. Um novo POST /v1/library para o mesmo vídeo restaura a linha em vez de criar duplicata.

SDKs oficiais

Use nossas bibliotecas oficiais para integração rápida:

Linguagem	Repositório
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 completo: github.com/SubDownload/api-sdk

→ Para cobrança, limites de taxa e códigos de erro veja Suporte e cobrança.

A documentação para desenvolvedores é publicada em inglês. A navegação lateral segue o idioma escolhido.

Referência da API

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

Endpoints

GET /v1/verify free

Verifica se uma API Key é válida. Retorna informações de token e usuário. Não consome créditos.

Requisição

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

Resposta 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

Obtém a transcrição / legendas de um vídeo do YouTube. Aceita ID de vídeo ou qualquer URL YouTube válida (watch, youtu.be, shorts).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`video_id`	string	OBRIGATÓRIO	ID de vídeo de 11 caracteres ou URL completa do YouTube. Alias: `video_url`.
`lang`	string	opcional	Códigos de idioma preferidos, separados por vírgula (ex.: `en,zh,ja`).

Requisição

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

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

Erros

400 video_id faltando · 404 sem legendas · 402 créditos esgotados

GET /v1/youtube/search 1 credit

Busca no YouTube vídeos ou canais que correspondem a uma palavra-chave.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`q`	string	OBRIGATÓRIO	Consulta de busca (1-200 caracteres).
`type`	string	opcional	`video` (padrão) ou `channel`.
`limit`	integer	opcional	1-50 resultados (padrão 20).

Requisição

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

Resolve qualquer referência de canal (@handle, URL ou ID UC…) para info canônica do canal.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`input`	string	OBRIGATÓRIO	@handle, URL do canal, URL do vídeo ou ID UC…

GET /v1/youtube/channel/search 1 credit

Busca dentro dos vídeos de um canal específico.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	OBRIGATÓRIO	@handle, URL ou ID UC… (alias: `channel_id`).
`q`	string	OBRIGATÓRIO	Consulta de busca.
`limit`	integer	opcional	1-50 (padrão 30).

GET /v1/youtube/channel/latest free

Busca os ~15 vídeos mais recentes de um canal via RSS. Rápido e grátis.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	OBRIGATÓRIO	@handle, URL ou ID UC… (alias: `channel_id`).

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

Lista todos os vídeos enviados por um canal, paginado ~100 por página.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`channel`	string	primeira pág.	@handle, URL ou ID UC… (alias: `channel_id`).
`continuation`	string	próx. págs.	Token retornado pela chamada anterior.

Nota: forneça channel OU continuation, não ambos.

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

Lista vídeos em uma playlist do YouTube com paginação.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`playlist`	string	primeira pág.	URL ou ID da playlist (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	próx. págs.	Token da resposta anterior.

Transcrição por IA (ASR)

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

Inicia uma transcrição AI Whisper assíncrona. Retorna task_id e dicas de ETA para cadenciar o polling.

Corpo (JSON)

Nome	Tipo	Obrigatório	Descrição
`video_url`	string	OBRIGATÓRIO	URL do YouTube (watch / youtu.be / shorts / embed).
`lang`	string	opcional	Dica de idioma (`en`, `pt`…). Omita para detecção automática.

Requisição

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

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

Respeite next_poll_after_seconds entre polls. Com cache hit, status=done volta imediatamente com os segments inline.

GET /v1/youtube/asr/{task_id} grátis

Consulta uma tarefa ASR. Grátis — sem créditos e sem cota de token. Apenas o criador pode ler.

Status: queued · downloading · transcribing · done · failed · cancelled. Os segments só são finais em status=done.

Library (biblioteca do usuário)

Armazenamento por usuário para transcrições salvas e resumos de IA. Leituras grátis; escritas consomem uma unidade de cota de token. Sem créditos de usuário.

GET /v1/library grátis

Lista itens que o usuário salvou na sua Library (transcrições + resumos).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`favorite`	string	opcional	`1` ou `true` para retornar só favoritos.
`q`	string	opcional	Correspondência parcial em título/autor.
`tag`	string	opcional	Filtro por tag.
`limit`	integer	opcional	1–100 (padrão 20).
`offset`	integer	opcional	Offset de paginação.

GET /v1/library/{id} grátis

Obtém os metadados de um item Library. Use has_asr / has_summary para decidir qual endpoint de conteúdo chamar em seguida.

GET /v1/library/{id}/transcript grátis

Retorna os segments ASR e o texto concatenado. 404 se não houver ASR concluído.

GET /v1/library/{id}/summary grátis

Retorna o texto do resumo armazenado. Use ?locale= para escolher entre locales salvos (padrão Accept-Language, depois en). 404 quando não há resumo para (video_id, locale).

POST /v1/library grátis (1 cota de token)

Corpo (JSON)

Nome	Tipo	Obrigatório	Descrição
`video_id`	string	OBRIGATÓRIO	ID do vídeo do YouTube.
`kind`	string	OBRIGATÓRIO	`asr` ou `summary`.
`title / author / thumbnail / video_url / language / tag`	string	opcional	Metadados para exibição / filtragem.
`locale`	string	modo summary	Locale do resumo (padrão `Accept-Language` depois `en`).
`text`	string	se kind=summary	Texto do resumo a persistir.
`model`	string	opcional	Identificador do LLM (ex.: `claude-opus-4`).

DELETE /v1/library/{id} grátis

Soft-delete de um item Library. Um novo POST /v1/library para o mesmo vídeo restaura a linha em vez de criar duplicata.

SDKs oficiais

Use nossas bibliotecas oficiais para integração rápida:

Linguagem	Repositório
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 completo: github.com/SubDownload/api-sdk

→ Para cobrança, limites de taxa e códigos de erro veja Suporte e cobrança.