API de modelos da FreeRap

Autenticação

Envie o cabeçalho Authorization nos dois endpoints de tarefa. Use a chave sk_ completa de Configurações → API. Uma chave ausente ou inválida devolve HTTP 401. Nunca exponha a chave no código do navegador.

Authorization: Bearer <API_KEY>

Referência da API

O modelo fornece o prompt, o vídeo de referência e a banda sonora. O cliente fornece a imagem de referência e as opções de geração. URLs de callback não são aceitas; consulte a tarefa para obter os resultados.

Chamadas bem-sucedidas usam HTTP 200 com code 0, message ok e um objeto data. Erros de pedido usam code -1 e message. Uma consulta bem-sucedida pode informar uma geração que falhou em data.status.

Criar uma tarefa

Inicia uma geração de vídeo assíncrona para um modelo ativo. HTTP 200 confirma a criação da tarefa; o vídeo ainda está em processamento.

Cabeçalhos obrigatórios: Authorization: Bearer <API_KEY> e Content-Type: application/json.

Parâmetros de caminho

Corpo do pedido

Integrações novas usam reference_image_urls, model e resolution. Estes são os campos comuns de todos os modelos.

Resposta de sucesso

Só valores de exemplo. A quantia de 30 créditos é ilustrativa; use a cotação devolvida pelo seu pedido.

{
  "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 uma tarefa

Devolve o estado atual de uma tarefa criada pela API e pertencente ao usuário da chave. Sem corpo do pedido. Use a mesma chave da criação, ou outra chave válida do mesmo usuário.

Resposta de sucesso

{
  "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 da tarefa

Consulte cerca de cada 30 segundos. Pare num estado terminal. Um tempo esgotado na consulta não significa que a geração falhou; consulte a mesma tarefa de novo.

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

Erros

Erros de pedido usam um estado HTTP fora de 2xx e o corpo abaixo. code é sempre -1 nestes erros; distinga as categorias pelo estado HTTP. message é um texto explicativo, não um identificador estável para máquina.

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

Créditos e limites

Os créditos são reservados quando a tarefa é criada. Enquanto estiver pending ou processing, credits_charged é igual a credits_estimate. O sucesso mantém a cobrança. Falha ou cancelamento libera a reserva, menos qualquer taxa de falha configurada (padrão 0). Leia credits_charged na resposta terminal para o valor final.

Cada chave de API permite até 30 tarefas pending ou processing. Por instância do servidor, pedidos de criação ficam limitados a um por segundo e consultas a cinco por segundo por chave. HTTP 429 pode incluir Retry-After em segundos; quando estiver ausente, espere antes de tentar de novo.