API REST DE PRODUCIÓN · v1

Constrúe descargas con YTSave

Resolve unha URL pública de medios, selecciona un formato exacto, crea un traballo asincrónico e entrega o resultado asinado ao teu usuario. A mesma cadea de produción limitada alimenta o sitio web YTSave.

YTSaveClientJSON sobre HTTPSTraballos asincrónicosCredenciais con ámbito

Inicio rápido

YTSave xestiona o host da API identificando primeiro as credenciais activadas por soporte. Segue cun punto final asignado ao inquilino e mantén visible un camiño de chamada só para o servidor.

URL do inquilinohttps://ytsave.app

AutenticaciónX-API-Key: ys_live_…

Perfil do clienteYTSaveClient

Versión da APIv1

# Available only after support activation
export YTSAVE_API_KEY="issued-after-review"

curl -X POST https://ytsave.app/v1/resolve \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

Para explicar a seguridade das Credenciais, YTSave separa o almacenamento secreto do lado do servidor da non incrustación no paquete do cliente. Un rexistro de evidencias non lle dá a ningún rexistro público ou repositorio un lugar propio.

Resolver un enlace

YTSave xestiona a operación Resolver identificando primeiro a detección da fonte. Segue cos formatos dunha URL enviada e non mantén saídas inventadas na vista.

POST/v1/resolveÁmbito: resolver

Campo	Tipo	Requirido	Descrición
`url`	URL HTTPS	Si	Páxina de medios pública ou autorizada para analizar.
`tenant`	cadea	Non	Dominio do inquilino asignado. Normalmente omitido.

{
  "success": true,
  "platform": "youtube",
  "title": "Example video",
  "formats": [
    {"id":"18","type":"video","quality":"360p","container":"mp4"}
  ],
  "cached": false
}

Para explicar o identificador de Formato, YTSave separa o valor devolto sen cambios da dispoñibilidade por enlace. Un rexistro de evidencias non lle dá un lugar propio a ningunha etiqueta de calidade suposta.

Crear e seguir un traballo de descarga

Para a creación de Traballos, YTSave comeza coa preparación asíncrona. O seu rexistro de evidencias combina iso cunha solicitude HTTP curta e remata coa execución limitada do traballador.

POST/v1/jobsÁmbito: empregos

Campo	Tipo	Requirido	Descrición
`url`	URL HTTPS	Si	A mesma fonte normalizada enviada para resolver.
`format_id`	cadea	Si	Un ID exacto da resposta de resolución.
`tenant`	cadea	Non	Dominio do inquilino asignado. Normalmente omitido.

curl -X POST https://ytsave.app/v1/jobs \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format_id":"18"}'

1202 AceptadoGardar job_id.

2Estado da enquisaGET /v1/jobs/{job_id} co mesmo chave.

3ListoAbrir a URL de descarga asinada.

Estado	Significado	Acción do cliente
`queued`	Admitido na cola limitada.	Volver a preguntar con retroceso.
`extracting`	Actualizando os metadatos da fonte ou a ruta.	Continuar sondaxe.
`processing`	Descargando, remuxeando ou fusionando.	Mostrar progreso do servidor.
`ready`	A descarga asinada está dispoñible.	Enviar a URL ao usuario.
`failed`	Erro estruturado do terminal.	Ler `error_code`. Reintentar só cando se indique.
`expired`	A saída temporal foi eliminada.	Crear un novo traballo.

curl https://ytsave.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

YTSave facilita a sondaxe de traballos. A páxina comeza cunha espera inicial de un segundo, pasa a un retroceso limitado e indica claramente a entrega asinada temporal.

Erros previsibles

Para o contrato de erro, YTSave comproba un sobre non 2xx antes dun ID de solicitude de soporte. Este rexistro de evidencias tamén aclara o manexo previsible do cliente.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "category": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "retryable": true,
    "details": {"retry_after_seconds": 20}
  },
  "request_id": "…"
}

HTTP	Significado típico	Acción
400	URL, corpo ou formato non dispoñible inválido.	Corrixa a solicitude. Resolva de novo para os formatos.
401	Chave ausente, inválida, caducada ou con ámbito incorrecto.	Comproba a credencial do lado do servidor.
403	A política do inquilino ou da fonte rexeitou a solicitude.	Non evites a política. Contacta co soporte.
404	Traballo descoñecido ou caducado.	Crear un novo traballo se é apropiado.
429	Limite de solicitudes ou traballos activos alcanzado.	Honra `retry_after_seconds`.
503	Fila/capacidade ou subida temporalmente non dispoñible.	Reintenta con retroceso exponencial e variación.

Contrato operativo

YTSave emite unha cota operativa con cada aprobación para protexer o consumidor da API e os servizos de medios ascendentes.

Use lóxica de aplicación idempotente e nunca inicie traballos duplicados para o mesmo clic do usuario.
Almacene en caché os metadatos brevemente, pero sempre trate as URLs de descarga asinadas como que expiran.
Usar retroceso exponencial limitado con variación para 429, 503 e erros que se poden reintentar.
Procesa só medios públicos ou medios aos que estás autorizado a acceder. Non se eluden os controis de DRM e acceso.
Mantén os IDs de solicitude e os IDs de traballo nos rexistros operativos privados. Non rexistres URLs enviadas innecesariamente.

YTSave xestiona o acceso ao Esquema identificando primeiro a activación antes da exploración. Segue coa autenticación asignada e mantén visibles as formas de solicitude documentadas. Referencia OpenAPI

ACCESO REVISADO POR OPERADOR

Solicita a túa clave API

Documenta o consumidor da API, a súa estimación mensual de solicitudes e os requisitos da plataforma admitidos. YTSave revisa se a resolución, o envío de traballo ou ambos están xustificados antes de emitir unha clave visible unha vez.

Solicitar acceso á API As chaves teñen ámbito de inquilino, son revogables e emítense a través do formulario de contacto. Os scripts anónimos non poden executar traballos de descargador.