Developers

API Heliun

Gere imagens e vídeos por HTTP usando sua conta, seus créditos e seu plano.

Visão geral

Base URL: https://heliun.pics/api/v1. Todas as respostas são JSON. A API usa os mesmos créditos e limites do site.

POST /api/v1/generate

GET /api/v1/jobs/{id}

GET /api/v1/me

GET /api/v1/plans

Autenticação

Crie uma chave em Perfil → API. Envie no cabeçalho:

Authorization: Bearer hl_sua_chave_aqui

Nunca exponha a chave no front-end. Use sempre no servidor.

Criar geração

POST /api/v1/generate

{
  "type": "video",            // "image", "video" ou "video_frames"
  "prompt": "ondas quebrando ao pôr do sol, câmera lenta",
  "aspect_ratio": "9:16",     // opcional (vídeo: 9:16 ou 16:9)
  "duration": 8,              // vídeo: fixo em 8s na API atual
  "start_job_id": 111,        // video_frames: job de uma imagem sua
  "end_job_id": 222,          // video_frames: job de outra imagem sua
  "negative_prompt": "texto"  // opcional
}

Exemplo em PHP

<?php
$ch = curl_init('https://heliun.pics/api/v1/generate');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer hl_sua_chave',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'image',
    'prompt' => 'retrato editorial com luz azul fria, fundo de concreto',
    'aspect_ratio' => '1:1',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
print_r($res);

Exemplo com cURL

curl -X POST https://heliun.pics/api/v1/generate \
  -H "Authorization: Bearer hl_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"type":"video","prompt":"cidade neon sob chuva, câmera lenta","duration":8}'

Resposta (HTTP 202):

{
  "ok": true,
  "job_id": 1234,
  "status": "pending",
  "type": "video",
  "credits_cost": 5,
  "poll_url": "https://heliun.pics/api/v1/jobs/1234"
}

Vídeo frame a frame

{
  "type": "video_frames",
  "start_job_id": 111,
  "end_job_id": 222,
  "prompt": "a câmera avança e a luz muda do dia para a noite",
  "aspect_ratio": "9:16"
}

Envie dois jobs de imagem concluídos da sua conta. O primeiro vira o frame inicial e o segundo o final; a IA cria o movimento entre eles em 8 segundos. Usa o mesmo modelo do vídeo normal: veo_3_1_t2v_lite_low_priority.

Consultar job

GET /api/v1/jobs/{id}

{
  "ok": true,
  "job_id": 1234,
  "type": "video",
  "status": "completed",   // pending | processing | completed | failed
  "result_url": "https://heliun.pics/uploads/videos/....mp4",
  "error": null,
  "credits_cost": 5
}

Recomendamos polling a cada 3–5 segundos. Em caso de falha, os créditos são devolvidos automaticamente.

Sua conta

GET /api/v1/me retorna créditos, plano ativo, uso do dia e custos atuais.

Planos

GET /api/v1/plans lista os planos públicos com preços em centavos.

Códigos de erro

Código	Significado
401	Chave ausente ou inválida.
403	Conta suspensa ou API desativada.
422	Parâmetros inválidos ou créditos insuficientes.
429	Limite de requisições atingido.
500	Erro interno. Tente novamente.

Limites

60 requisições de geração por minuto por chave.
Créditos: imagem 1, vídeo 5.
Planos ilimitados seguem o uso justo diário do plano.
Uma chave pode ser revogada a qualquer momento no perfil.