Documentacion API

Aprende a usar la API de DownMagic paso a paso

Guia practica para autenticarte, crear peticiones, controlar creditos, restringir IPs y manejar errores en produccion.

Base URL

Esta es la URL oficial para integrar DownMagic API en produccion. Todas las peticiones deben salir desde un backend seguro y autenticarse con una API key activa.

https://api.downmagic.com

Quickstart

Contrata o activa un plan

La API de cliente exige suscripcion activa antes de crear o usar claves.

Crea una API key

Entra en el panel, crea la key y copia el secreto completo. No se vuelve a mostrar.

Haz la primera peticion

Envia Authorization: Bearer dm_live_... y revisa los headers de consumo.

Acceso y pago

Las API keys de cliente solo se pueden crear y usar cuando la cuenta tiene una suscripcion API activa.

El administrador puede dar de alta usuarios y planes desde el panel.

El cliente contrata o cambia su plan desde Billing.

Las cuentas admin pueden operar internamente sin bloqueo de pago.

Autenticacion

Envia tu API key en cada peticion privada. El secreto completo solo se muestra una vez al crear o rotar la key.

Header recomendado: Authorization: Bearer dm_live_...

Header alternativo: x-downmagic-key: dm_live_...

No expongas la key en frontend publico, apps moviles sin backend o repositorios.

Seguridad por IP

Cada key puede limitarse a IPs exactas o rangos CIDR para reducir el riesgo si el secreto se filtra.

Ejemplo de IP exacta: 203.0.113.10.

Ejemplo de CIDR: 203.0.113.0/24.

Si no configuras allowlist, la key se acepta desde cualquier IP mientras el plan y los limites esten activos.

Creditos y limites

Cada request procesada registra uso mensual por cuenta y por API key.

El endpoint de eliminar fondos consume 1 credito por imagen procesada.

Puedes limitar creditos mensuales por key desde el panel.

La respuesta incluye headers de creditos usados y restantes cuando aplica.

Jobs asincronos

Las tareas largas de conversion y descarga se crean como jobs para que tu backend pueda consultar progreso y descargar el resultado cuando este listo.

Crea el job con /convert o /download.

Consulta progreso con /jobs/{jobId}.

Descarga el archivo final con /jobs/{jobId}/download antes de que expire.

Endpoints v1

Peticiones disponibles

En api.downmagic.com puedes usar rutas limpias como /usage o /background/remove. La version actual mantiene contratos estables para que tus integraciones puedan evolucionar sin cambios inesperados.

GET/healthPublico0 creditos

Estado de la API

Comprueba que api.downmagic.com y la base de datos estan disponibles.

Detalles

Usalo desde monitores externos, health checks de despliegue o diagnostico rapido.

No requiere API key.

Request

Sin body.

Sin autenticacion.

Response

JSON con ok, service, version y checks internos.

cURL

curl "https://api.downmagic.com/health"

Respuesta

{
  "ok": true,
  "service": "downmagic-api",
  "version": "v1",
  "checks": {
    "api": { "ok": true },
    "databaseConfigured": { "ok": true },
    "database": { "ok": true }
  }
}

GET/usageAPI key requerida0 creditos

Consumo mensual

Devuelve el consumo mensual de la cuenta autenticada y el plan asociado.

Detalles

Ideal para dashboards propios, alertas internas o mostrar consumo a tus clientes.

El consumo se agrupa por servicio y se reinicia por periodo mensual.

Request

Header Authorization obligatorio.

Sin body.

Response

JSON con account y usage: usedCredits, requestCount, byService, limit, remaining y percentage.

cURL

curl "https://api.downmagic.com/usage" \
  -H "Authorization: Bearer dm_live_your_api_key"

JavaScript

const res = await fetch("https://api.downmagic.com/usage", {
  headers: {
    Authorization: `Bearer ${process.env.DOWNMAGIC_API_KEY}`,
  },
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();

POST/background/removeAPI key requerida1 credito por imagen

Eliminar fondo de imagen

Procesa una imagen y devuelve un PNG con fondo transparente.

Detalles

Acepta multipart/form-data con el campo file.

Formatos soportados: JPG, PNG, WEBP, AVIF y HEIC.

Limites por defecto: 40 MB e imagenes hasta 7680 x 4320 px, configurables por entorno.

La respuesta es binaria image/png; guardala como archivo o Blob.

Request

Header Authorization obligatorio.

Content-Type multipart/form-data.

Campo file con la imagen original.

Response

Body binario PNG con transparencia.

Header x-downmagic-credits-used con el uso mensual actualizado.

Header x-downmagic-credits-remaining con creditos restantes si el plan tiene limite.

cURL

curl -X POST "https://api.downmagic.com/background/remove" \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -F "[email protected]" \
  --output portrait_downmagic.png

JavaScript

const form = new FormData();
form.append("file", fileInput.files[0]);

const res = await fetch("https://api.downmagic.com/background/remove", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
  body: form,
});

if (!res.ok) throw new Error(await res.text());
const transparentPng = await res.blob();

Python

import requests

with open("portrait.jpg", "rb") as image:
    response = requests.post(
        "https://api.downmagic.com/background/remove",
        headers={"Authorization": "Bearer dm_live_your_api_key"},
        files={"file": image},
        timeout=300,
    )

response.raise_for_status()
with open("portrait_downmagic.png", "wb") as output:
    output.write(response.content)

POST/convertAPI key requerida1 credito por job completado

Convertir archivos

Sube un archivo y crea un job para convertirlo a otro formato.

Detalles

Acepta multipart/form-data con el campo file.

Soporta conversion de video, audio e imagen segun el registro de formatos de DownMagic.

Devuelve 202 Accepted con jobId, statusUrl y downloadUrl.

El resultado expira automaticamente para no almacenar archivos de forma permanente.

Request

Header Authorization obligatorio.

Campo file con el archivo original.

Campo outputFormat obligatorio, por ejemplo mp4, mp3, webp, png o gif.

Campo quality opcional: source, 1080, 720, 480, high, medium, small, large.

Response

JSON con job, statusUrl, downloadUrl, inputFormat y outputFormat.

Consulta /jobs/{jobId} hasta que state sea COMPLETED.

Descarga el resultado en /jobs/{jobId}/download.

cURL

curl -X POST "https://api.downmagic.com/convert" \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -F "[email protected]" \
  -F "outputFormat=mp4" \
  -F "quality=720"

JavaScript

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("outputFormat", "mp3");
form.append("quality", "high");

const res = await fetch("https://api.downmagic.com/convert", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});

const job = await res.json();

POST/downloadAPI key requerida1 credito por job completado

Descargar y convertir desde URL

Crea un job para descargar contenido autorizado desde una URL y devolver MP4, MP3 u otro formato soportado.

Detalles

Pensado para flujos como YouTube a MP4, YouTube a MP3 y plataformas soportadas por yt-dlp.

Requiere ownershipConfirmed=true para confirmar que tienes derecho a procesar ese contenido.

Usa la misma cola, WARP/POT, Redis y worker que la aplicacion web.

Devuelve un job asincrono; no bloquees tu servidor esperando el archivo en la peticion inicial.

Request

Header Authorization obligatorio.

Body JSON con url.

outputFormat opcional; si no se envia, se usa el formato de origen detectado.

quality opcional: source, 1080, 720, 480 para video; high, medium, small para audio.

ownershipConfirmed debe ser true.

Response

JSON 202 con jobId, provider, title, durationSec, statusUrl y downloadUrl.

Consulta /jobs/{jobId} para progreso.

Descarga el archivo cuando state sea COMPLETED.

YouTube a MP4

curl -X POST "https://api.downmagic.com/download" \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "outputFormat": "mp4",
    "quality": "720",
    "ownershipConfirmed": true
  }'

YouTube a MP3

const res = await fetch("https://api.downmagic.com/download", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=VIDEO_ID",
    outputFormat: "mp3",
    quality: "high",
    ownershipConfirmed: true,
  }),
});

const job = await res.json();

GET/jobs/{jobId}API key requerida0 creditos

Consultar estado de job

Devuelve estado, progreso, formato final y enlace de descarga de un job creado por tu cuenta.

Detalles

Sirve para jobs creados con /convert y /download.

Solo la cuenta propietaria puede consultar el job.

Estados habituales: QUEUED, DOWNLOADING, ANALYZING, PROCESSING, FINALIZING, COMPLETED y FAILED.

Request

Header Authorization obligatorio.

Sin body.

Response

JSON con job, statusUrl, downloadUrl y downloadReady.

Cuando downloadReady sea true, llama a /jobs/{jobId}/download.

cURL

curl "https://api.downmagic.com/jobs/job_123" \
  -H "Authorization: Bearer dm_live_your_api_key"

Respuesta

{
  "job": {
    "id": "job_123",
    "state": "COMPLETED",
    "progress": 100,
    "outputFormat": "mp4",
    "fileName": "clip_downmagic.mp4"
  },
  "downloadReady": true,
  "downloadUrl": "https://api.downmagic.com/jobs/job_123/download"
}

GET/jobs/{jobId}/downloadAPI key requerida0 creditos

Descargar resultado de job

Devuelve el archivo final de un job completado.

Detalles

La respuesta es binaria, no JSON.

Incluye Content-Disposition con nombre de archivo acabado en _downmagic.

El resultado expira automaticamente segun la politica de retencion.

Request

Header Authorization obligatorio.

El job debe estar COMPLETED.

Response

Body binario con el archivo convertido o descargado.

Content-Type segun formato final.

cURL

curl "https://api.downmagic.com/jobs/job_123/download" \
  -H "Authorization: Bearer dm_live_your_api_key" \
  --output result_downmagic.mp4

Errores y respuestas

Los errores JSON siguen la forma { error: { code, message } }.

HTTP	Code	Significado
401	`missing_api_key`	No se envio API key.
401	`invalid_api_key`	La API key no existe o no coincide.
402	`payment_required`	La cuenta necesita una suscripcion API activa.
402	`usage_limit_reached`	La cuenta llego al limite mensual del plan.
402	`api_key_limit_reached`	La key llego a su limite mensual propio.
403	`ip_not_allowed`	La IP origen no esta permitida para esa key.
403	`api_access_disabled`	La cuenta o key esta desactivada.
403	`api_key_expired`	La key ha caducado.
413	`file_too_large`	La imagen supera el limite configurado.
415	`unsupported_format`	Formato no soportado para ese endpoint.
409	`job_not_ready`	El job todavia no ha terminado.
404	`job_not_found`	El job no existe, no pertenece a esa cuenta o ha expirado.
503	`queue_full`	La cola esta llena temporalmente.
500	`processing_failed`	No se pudo completar el procesamiento.
503	`api_database_not_configured`	La plataforma API no tiene base de datos disponible.

Proximos servicios API

Estos servicios ya existen como flujo de producto o infraestructura, pero se documentaran como endpoint publico cuando el contrato sea estable.

Transcripcion API

La transcripcion se expondra cuando el motor Cloudflare/Whisper quede activado de forma estable para produccion.