Referencia Técnica de
VideoStack API
Descubre cómo integrar procesamiento de video y audio acelerado por IA en tus aplicaciones con nuestra infraestructura escalable multi-GPU.
/Autenticación
La API requiere autenticación mediante API Key en todos los endpoints privados. Debes incluir tu clave en el header `X-API-Key`.
curl -X GET "https://api.tudominio.com/" \
-H "X-API-Key: tu_api_key_secreta"HTTP/1.1 200 OK
Content-Type: application/json
{
"message": "API de Procesamiento de Video - Multi-GPU Optimizada",
"gpus": ["NVIDIA RTX 4090"]
}/health/metricsHealth & Metrics
Obtén estadísticas globales de uso de recursos, RAM, CPU y número de peticiones para monitorear tu cuota.
curl -X GET "https://api.tudominio.com/health/metrics" \
-H "X-API-Key: tu_api_key_secreta"HTTP/1.1 200 OK
Content-Type: application/json
{
"monitoring_enabled": true,
"total_requests": 150,
"active_requests": 2,
"endpoints": {
"POST /video/join": {
"request_count": 50,
"ram_peak_mb": 2500.5,
"cpu_avg_percent": 45.1
}
}
}/subtitles/generateGenerar Subtítulos Animados
Genera subtítulos automáticos ultra rápidos usando Whisper V3 y los incrusta en el video con efectos altamente personalizables.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL pública del video original. |
| style_options.effect | string | karaoke_fill | Efectos soportados: simple_srt, highlight_word_by_word, karaoke_fill, fade_per_line, zoom_in_word, slide_up_line, gentle_popup_line, typewriter_word, zoom_and_highlight_word, multi_color_highlight, multi_color_zoom_highlight, neon_highlight_word, neon_zoom_highlight_word |
| style_options.max_words_per_line | number | 5 | Límite de palabras mostradas simultáneamente. |
| style_options.font_name | string | Arial | Nombre de la fuente (debe estar instalada en servidor). |
| style_options.font_size | number | 60 | Tamaño de la fuente. |
| style_options.primary_color | string | #FFFFFF | Color principal en formato HEX. |
| style_options.secondary_color | string | #808080 | Color secundario para palabras pasadas o inactivas. |
| style_options.position_alignment | number | 2 | Alineación usando teclado numérico (2 = Centro abajo, 5 = Centro medio, 8 = Centro arriba). |
curl -X POST "https://api.tudominio.com/subtitles/generate" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"style_options": {
"effect": "neon_zoom_highlight_word",
"font_size": 75,
"primary_color": "#00FFFF",
"secondary_color": "#FF00FF"
}
}' \
--output subtitulado.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="video_sub.mp4"
Content-Length: 14502391
<binary_data>/transcribeTranscribir Video
Extrae el texto de un video directo o de YouTube de forma inteligente, retornando JSON, SRT, VTT o Texto plano.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video (MP4) o link de YouTube. |
| language | string | auto | Código de idioma (ej: es, en). |
| output_format | string | json | json, text, srt, vtt. |
| include_timestamps | boolean | true | Incluye marcas de tiempo por segmento. |
| include_word_timestamps | boolean | false | Incluye marcas de tiempo a nivel de palabra individual. |
curl -X POST "https://api.tudominio.com/transcribe" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://youtube.com/watch?v=12345",
"language": "es",
"output_format": "json",
"include_word_timestamps": true
}'HTTP/1.1 200 OK
Content-Type: application/json
{
"text": "Hola a todos, bienvenidos al tutorial...",
"language": "es",
"duration": 125.5,
"source": "youtube",
"format": "json",
"segments": [
{ "start": 0.0, "end": 3.5, "text": "Hola a todos, bienvenidos al tutorial" }
],
"word_timestamps": [
{ "word": "Hola", "start": 0.0, "end": 0.5 },
{ "word": "a", "start": 0.5, "end": 0.7 }
]
}/subtitles/translateTraducir Transcripción
Transcribe el video y automáticamente traduce los subtítulos al idioma destino.
Idiomas de Traducción Soportados
La API de traducción utiliza los códigos de idioma estándar ISO-639-1. A continuación se muestran los idiomas más comunes.
Soporta virtualmente todos los idiomas globales de Google Translate.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video original. |
| target_lang | string | en | Idioma destino (ej: en, fr, de). |
curl -X POST "https://api.tudominio.com/subtitles/translate" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/spanish_video.mp4",
"target_lang": "en"
}'HTTP/1.1 200 OK
Content-Type: application/json
{
"text": "Hello everyone, welcome to the tutorial...",
"segments": [
{ "start": 0.0, "end": 3.5, "text": "Hello everyone, welcome to the tutorial" }
]
}/video/joinFusión Masiva de Videos
Une múltiples clips de video normalizando el audio y aplicando transiciones suaves entre ellos. Gestiona automáticamente la RAM (Batch Processing) para videos pesados.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_urls | string[] | - | Array de URLs de los videos (mínimo 2). |
| transition_options.global_effect | string | fade | fade, fadeblack, fadewhite, distance, wipeleft, wiperight, wipeup, wipedown, slideleft, slideright, circlecrop, rectcrop, dissolve, pixelize, radial, hblur, diagtl, diagtr. |
| transition_options.duration | number | 1.0 | Duración de la transición en segundos. |
curl -X POST "https://api.tudominio.com/video/join" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_urls": [
"https://example.com/clip1.mp4",
"https://example.com/clip2.mp4"
],
"transition_options": {
"global_effect": "fadeblack",
"duration": 1.5
}
}' \
--output final_video.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="joined_video.mp4"
Content-Length: 45091223
<binary_data>/video/editEdición Genérica (FFmpeg)
Libertad total. Envía comandos FFmpeg crudos para aplicar filtros complejos de video y audio. Soporta sintaxis de duración dinámica ('T').
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
| audio_url | string | - | (Opcional) URL de audio adicional. |
| commands | object[] | - | Array de pares {option, value}. Usa 'T' en el value para referenciar la duración total (ej: 'T-5'). |
curl -X POST "https://api.tudominio.com/video/edit" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"commands": [
{"option": "-vf", "value": "scale=1920:1080,fps=30"},
{"option": "-c:v", "value": "libx264"},
{"option": "-preset", "value": "veryfast"}
]
}' \
--output edited_video.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="output.mp4"
Content-Length: 12053412
<binary_data>/video/jumpcutJumpcut Automático (Silencios)
Analiza el audio del video y elimina automáticamente los silencios, ideal para vlogs, podcasts o tutoriales para retener audiencia.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
| silence_db | string | -30dB | Umbral de ruido para considerar silencio. |
| silence_duration | number | 0.5 | Duración mínima en segundos para cortar. |
| padding | number | 0.2 | Margen de seguridad (seg) alrededor de los cortes para evitar voces cortadas. |
curl -X POST "https://api.tudominio.com/video/jumpcut" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/podcast.mp4",
"silence_db": "-35dB",
"silence_duration": 0.8,
"padding": 0.25
}' \
--output podcast_jumpcut.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="jumpcut.mp4"
Content-Length: 9540321
<binary_data>/video/smartcropSmart Crop (TikTok/Reels)
Recorta un video horizontal (16:9) al formato vertical (9:16) desenfocando los bordes u optimizando el encuadre central automáticamente.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video horizontal. |
curl -X POST "https://api.tudominio.com/video/smartcrop" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/horizontal_video.mp4"
}' \
--output tiktok_video.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="smartcrop.mp4"
Content-Length: 15403210
<binary_data>/video/clipExtraer Clip de Video
Extrae un segmento específico de un video usando tiempos exactos sin recodificar (cuando es posible) para máxima velocidad.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
| start_time | string | - | Tiempo de inicio (ej: '00:01:20' o '80'). |
| end_time | string | - | Tiempo de fin (ej: '00:02:00' o '120'). |
curl -X POST "https://api.tudominio.com/video/clip" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"start_time": "00:00:15",
"end_time": "00:00:45"
}' \
--output clip.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="clip.mp4"
Content-Length: 450321
<binary_data>/video/thumbnailGenerar Miniatura
Extrae un fotograma exacto del video para usarlo como miniatura o portada (JPEG).
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
| timestamp | string | 00:00:01 | Marca de tiempo del fotograma a extraer. |
curl -X POST "https://api.tudominio.com/video/thumbnail" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"timestamp": "00:01:30"
}' \
--output miniatura.jpgHTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: attachment; filename="thumbnail.jpg"
Content-Length: 204561
<binary_data>/video/watermarkAñadir Marca de Agua
Superpone una imagen (logo) sobre el video en una posición específica.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
| image_url | string | - | URL de la imagen (PNG transparente ideal). |
| position | string | bottom-right | top-left, top-right, bottom-left, bottom-right, center. |
curl -X POST "https://api.tudominio.com/video/watermark" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"image_url": "https://example.com/logo.png",
"position": "top-left"
}' \
--output video_watermarked.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="watermark.mp4"
Content-Length: 18450123
<binary_data>/video/compressCompresión Masiva
Reduce dramáticamente el tamaño del archivo de video optimizando su resolución y bitrate mediante codificación de hardware (QSV/NVENC).
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video pesado. |
| resolution | string | 720 | Resolución vertical máxima (1080, 720, 480). |
| crf | string | 28 | Constant Rate Factor (Calidad). Menor valor = Más calidad/peso. (23 a 28 es óptimo). |
curl -X POST "https://api.tudominio.com/video/compress" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/heavy_4k.mp4",
"resolution": "720",
"crf": "26"
}' \
--output video_compressed.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="compressed.mp4"
Content-Length: 8450123
<binary_data>/audio/extractExtraer Audio
Separa y exporta la pista de audio de cualquier archivo de video sin pérdida de calidad (copia directa del codec).
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video. |
curl -X POST "https://api.tudominio.com/audio/extract" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4"
}' \
--output audio_extraido.mp3HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="audio.mp3"
Content-Length: 4501230
<binary_data>/audio/enhanceLimpiar y Mejorar Audio (IA)
Aplica reducción de ruido, normalización de volumen, compresión y ecualización paramétrica para dar un tono de 'estudio' a voces caseras.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| audio_url | string | - | URL del audio o video de origen. |
curl -X POST "https://api.tudominio.com/audio/enhance" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://example.com/voice_memo.mp3"
}' \
--output audio_mejorado.mp3HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="enhanced_audio.mp3"
Content-Length: 3501230
<binary_data>/audio/ttsTexto a Voz (TTS)
Genera audio de alta calidad a partir de texto usando redes neuronales profundas de Edge TTS.
Catálogo de Voces e Idiomas Soportados
La API soporta traducciones a más de 100 idiomas (código ISO-639-1) y síntesis de voz con redes neuronales. Aquí listamos las voces de mayor calidad para los idiomas más populares.
Español (es) 🇪🇸 🇲🇽
- es-ES-AlvaroNeural (M)
- es-ES-ElviraNeural (F)
- es-MX-DaliaNeural (F)
- es-MX-JorgeNeural (M)
Inglés (en) 🇺🇸 🇬🇧
- en-US-AriaNeural (F)
- en-US-GuyNeural (M)
- en-GB-SoniaNeural (F)
- en-GB-RyanNeural (M)
Francés (fr) 🇫🇷
- fr-FR-DeniseNeural (F)
- fr-FR-HenriNeural (M)
Alemán (de) 🇩🇪
- de-DE-KatjaNeural (F)
- de-DE-ConradNeural (M)
Italiano (it) 🇮🇹
- it-IT-IsabellaNeural (F)
- it-IT-DiegoNeural (M)
Portugués (pt) 🇧🇷 🇵🇹
- pt-BR-FranciscaNeural (F)
- pt-BR-AntonioNeural (M)
- pt-PT-DuarteNeural (M)
Ver catálogo completo de 322 voces soportadas
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| text | string | - | Texto a sintetizar. |
| voice | string | es-ES-AlvaroNeural | Identificador de la voz. |
curl -X POST "https://api.tudominio.com/audio/tts" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"text": "Bienvenidos al tutorial oficial de VideoStack.",
"voice": "es-ES-ElviraNeural"
}' \
--output tts.mp3HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="tts_output.mp3"
Content-Length: 150123
<binary_data>/animate/imageAnimar Imagen Estática
Transforma una simple imagen JPG/PNG en un clip de video dinámico usando paneos y zooms automatizados, ideal para B-Roll o slideshows.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| image_url | string | - | URL de la imagen. |
| effect | string | zoom_in | zoom_in, zoom_out, pan_right, pan_left, pan_up, pan_down. |
| duration | number | 5 | Duración en segundos (1-60). |
| zoom_level | number | 1.5 | Intensidad del zoom (1.0 a 3.0). |
curl -X POST "https://api.tudominio.com/animate/image" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/photo.jpg",
"effect": "pan_right",
"duration": 8,
"zoom_level": 1.2
}' \
--output animated_image.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="animated_image.mp4"
Content-Length: 5450123
<binary_data>/video/dubDoblaje Automático IA
El pipeline definitivo: Transcribe el video, traduce el texto, genera el nuevo audio con TTS ajustando velocidades, aplica Audio Ducking al audio original y une todo en un nuevo video final.
Catálogo de Voces e Idiomas Soportados
La API soporta traducciones a más de 100 idiomas (código ISO-639-1) y síntesis de voz con redes neuronales. Aquí listamos las voces de mayor calidad para los idiomas más populares.
Español (es) 🇪🇸 🇲🇽
- es-ES-AlvaroNeural (M)
- es-ES-ElviraNeural (F)
- es-MX-DaliaNeural (F)
- es-MX-JorgeNeural (M)
Inglés (en) 🇺🇸 🇬🇧
- en-US-AriaNeural (F)
- en-US-GuyNeural (M)
- en-GB-SoniaNeural (F)
- en-GB-RyanNeural (M)
Francés (fr) 🇫🇷
- fr-FR-DeniseNeural (F)
- fr-FR-HenriNeural (M)
Alemán (de) 🇩🇪
- de-DE-KatjaNeural (F)
- de-DE-ConradNeural (M)
Italiano (it) 🇮🇹
- it-IT-IsabellaNeural (F)
- it-IT-DiegoNeural (M)
Portugués (pt) 🇧🇷 🇵🇹
- pt-BR-FranciscaNeural (F)
- pt-BR-AntonioNeural (M)
- pt-PT-DuarteNeural (M)
Ver catálogo completo de 322 voces soportadas
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| video_url | string | - | URL del video en idioma original. |
| target_lang | string | es | Idioma destino (ej: es, fr, en). |
| voice | string | es-ES-AlvaroNeural | Voz neuronal a utilizar en el nuevo idioma. |
curl -X POST "https://api.tudominio.com/video/dub" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/english_video.mp4",
"target_lang": "es",
"voice": "es-ES-AlvaroNeural"
}' \
--output video_doblado.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="dubbed_video.mp4"
Content-Length: 22450123
<binary_data>/download/mediaDescarga Universal de RRSS
Extrae el MP4 o MP3 subyacente de URLs de plataformas de redes sociales (YouTube, TikTok, Twitter, Instagram, etc) utilizando yt-dlp.
Parámetros (Body JSON)
| Nombre | Tipo | Default | Descripción |
|---|---|---|---|
| url | string | - | Enlace al post de la red social. |
| media_type | string | video | video o audio. |
curl -X POST "https://api.tudominio.com/download/media" \
-H "X-API-Key: tu_api_key_secreta" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.tiktok.com/@user/video/123456",
"media_type": "video"
}' \
--output social_video.mp4HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="tiktok_video.mp4"
Content-Length: 8450123
<binary_data>