API de plantillas de FreeRap

Autenticación

Envía Authorization en ambos endpoints de tareas con la clave sk_ completa de Ajustes → API. Una clave ausente o no válida devuelve HTTP 401. No la expongas en código del navegador.

Authorization: Bearer <API_KEY>

Convenciones de la API

La plantilla proporciona el prompt, el video de referencia y la banda sonora. El cliente envía la imagen y los parámetros. No hay callbacks; consulta la tarea.

Las solicitudes correctas devuelven HTTP 200, code 0, message ok y data. Los errores usan code -1 y message. Una consulta correcta puede indicar una generación fallida en data.status.

Crear una tarea

Inicia una generación asíncrona para una plantilla activa. HTTP 200 confirma la creación de la tarea; el video sigue procesándose.

Cabeceras obligatorias: Authorization: Bearer <API_KEY> y Content-Type: application/json.

Parámetros de ruta

Cuerpo de la solicitud

Las nuevas integraciones usan reference_image_urls, model y resolution. Los campos siguientes son comunes a todas las plantillas.

Respuesta correcta

Los valores son ilustrativos. Los 30 créditos no son una tarifa fija; usa el precio devuelto por tu solicitud.

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "credits_estimate": 30,
    "credits_charged": 30
  }
}

curl --request POST \
  'https://freerapvideo.com/api/v1/templates/YOUR_TEMPLATE_SLUG/generations' \
  --header "Authorization: Bearer $FREERAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "reference_image_urls": ["https://cdn.example.com/image-1.jpg", "https://cdn.example.com/image-2.jpg", "https://cdn.example.com/image-3.jpg"],
    "model": "pro",
    "resolution": "720p"
  }'

Consultar una tarea

Devuelve el estado de una tarea creada por API y perteneciente al usuario de la clave. Sin cuerpo. Usa la clave de creación u otra válida del mismo usuario.

Respuesta correcta

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "campaign": "bulin",
    "costCredits": 30,
    "credits_estimate": 30,
    "credits_charged": 30,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [
      "https://media.example.com/generated/video.mp4"
    ]
  }
}

Estados de tarea

Consulta cada 30 segundos aproximadamente y detente en un estado final. Un timeout de consulta no significa que la generación haya fallado; consulta la misma tarea.

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "campaign": "bulin",
    "costCredits": 0,
    "credits_estimate": 30,
    "credits_charged": 0,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [],
    "error": "Video generation failed."
  }
}

Errores

Los errores de solicitud usan un estado HTTP no 2xx y el cuerpo siguiente. code siempre es -1; distingue las categorías por estado HTTP. message es texto explicativo, no un identificador estable de error.

{
  "code": -1,
  "message": "Insufficient credits."
}

Créditos y límites

Los créditos se reservan al crear. Mientras la tarea está pending o processing, credits_charged equivale a credits_estimate. El éxito conserva el cargo; el fallo o cancelación libera la reserva menos la tarifa de fallo configurada (0 por defecto). El estado final indica el cargo definitivo.

Cada clave permite hasta 30 tareas pending o processing. Por instancia, cada clave admite una creación y cinco consultas por segundo. HTTP 429 puede incluir Retry-After en segundos; si falta, espera antes de reintentar.