API v1

Documentação da API

Gere imagem, vídeo, narração e avatar pelo seu código. Preço em reais, descontado do seu saldo. Para testar sem código, use o playground de cada modelo.

Visão geral

Item	Valor
URL base	`https://api.hubroque.com.br`
Autenticação	`Authorization: Bearer hr_...`
Formato	JSON (UTF-8)
Moeda	Reais (o saldo é pré-pago)

Tudo que gera arquivo é assíncrono:

Crie a tarefa e receba um taskId.
Espere o resultado: consulte o status ou receba o callback.
Baixe o arquivo pelo link do resultado.

Sempre confira o campo code no corpo. A resposta HTTP vem 200 mesmo quando há erro. É de propósito, para manter o formato que muitos apps já usam.

Já usa uma API no formato createTask / recordInfo? Troque a URL base e a chave. O resto do código continua igual.

Dinheiro e créditos equivalentes. A criação da tarefa desconta do seu saldo o preço em reais da tabela. Se a geração falhar, o valor volta sozinho. Nas respostas da API (saldo e creditsConsumed), os valores vêm em créditos equivalentes, para manter compatibilidade com apps que mostram créditos:

1 crédito equivalente = R$ 0,0648. Para converter: reais = créditos × 0,0648. Exemplo: uma geração de R$ 0,60 aparece como 9,26 créditos.

Autenticação

Mande a chave no cabeçalho Authorization de todo pedido. Nos pedidos com corpo JSON, mande também Content-Type: application/json.

Cabeçalhos

Authorization: Bearer hr_SUA_CHAVE
Content-Type: application/json

Crie a chave em Painel → Chaves de API. Ela aparece uma vez só: copie e guarde.
A chave usa o seu saldo. Trate como senha: nunca coloque em código que roda no navegador ou em app público.
Dá para pôr limite de gasto por dia em cada chave e revogar quando quiser.
Chave ausente, errada ou revogada: code: 401.

Primeira geração em 3 minutos

Crie uma conta e adicione saldo.
Crie uma chave de API.
Rode o exemplo abaixo trocando a chave.

curl -X POST "https://api.hubroque.com.br/api/v1/jobs/createTask" \
  -H "Authorization: Bearer hr_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "Tênis branco em fundo azul, luz de estúdio, foto de produto",
    "resolution": "1K"
  }
}'

# Depois, consulte o resultado com o taskId recebido:
curl "https://api.hubroque.com.br/api/v1/jobs/recordInfo?taskId=SEU_TASK_ID" \
  -H "Authorization: Bearer hr_SUA_CHAVE"

Criar tarefa

POST/api/v1/jobs/createTask

Campo	Tipo	Obrigatório	O que é
`model`	texto	sim	ID do modelo. Fica na página de cada modelo e no catálogo.
`input`	objeto	sim	Campos do modelo. Veja a aba README de cada modelo.
`callBackUrl`	URL	não	Recebe um POST quando a tarefa termina. Endereço público (http ou https).

curl -X POST "https://api.hubroque.com.br/api/v1/jobs/createTask" \
  -H "Authorization: Bearer hr_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "callBackUrl": "https://seusite.com.br/webhooks/hubroque",
  "input": {
    "prompt": "Tênis branco em fundo azul, luz de estúdio, foto de produto",
    "resolution": "1K"
  }
}'

Resposta

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "3f9c2a7be1d84c0f9a6b5e21c7d04a18" }
}

O preço é calculado pelo input e descontado na criação. Se a geração falhar, o valor volta.
Campo que o modelo não usa é ignorado. Opção que não tem preço na tabela é recusada (422), sem cobrança.
Sem saldo suficiente: 402, antes de criar. Nada é cobrado.
Arquivos de entrada (imagem, vídeo, áudio) vão como link público. Não tem link? Use o envio de arquivo.
Geração de música não está disponível (422).

Consultar tarefa

GET/api/v1/jobs/recordInfo?taskId=...

cURL

curl "https://api.hubroque.com.br/api/v1/jobs/recordInfo?taskId=3f9c2a7be1d84c0f9a6b5e21c7d04a18" \
  -H "Authorization: Bearer hr_SUA_CHAVE"

Resposta

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "3f9c2a7be1d84c0f9a6b5e21c7d04a18",
    "model": "nano-banana-2",
    "state": "success",
    "param": "{\"model\":\"nano-banana-2\",\"input\":\"{\\\"prompt\\\":\\\"...\\\"}\"}",
    "resultJson": "{\"resultUrls\":[\"https://.../resultados/3f9c2a7be1d84c0f9a6b5e21c7d04a18/0.png\"]}",
    "failCode": "",
    "failMsg": "",
    "costTime": 21,
    "completeTime": 1793660021000,
    "createTime": 1793660000000,
    "updateTime": 1793660021000,
    "creditsConsumed": 9.26
  }
}

Campo	O que é
`state`	Estado da tarefa (veja abaixo).
`resultJson`	Texto JSON. Com sucesso, traz `resultUrls`: a lista de links dos arquivos.
`param`	Texto JSON com o pedido original.
`failCode`	Código da falha, em texto (ex.: "400", "500").
`failMsg`	Motivo da falha, em português.
`costTime`	Segundos entre criar e terminar.
`createTime`	Criação, completeTime e updateTime: em milissegundos desde 1970.
`creditsConsumed`	Valor cobrado em créditos equivalentes. Zero enquanto gera e se falhar.

param e resultJson são texto: faça o parse. O resultado vem sempre em resultUrls, em todos os modelos.

Tarefa que não existe ou é de outra conta responde assim (mesma resposta nos dois casos):

Resposta

{ "code": 422, "msg": "recordInfo is null", "data": null }

Estados e tempos

state	Quer dizer
`waiting`	Recebida, ainda na fila.
`queuing`	Na fila do modelo.
`generating`	Gerando.
`success`	Pronta: leia `resultJson`.
`fail`	Falhou: veja `failCode` e `failMsg`. O valor já voltou para o saldo.

Imagem e áudio: consulte a cada 3 a 5 s. Costumam ficar prontos em menos de 1 min.
Vídeo: consulte a cada 10 a 15 s. Pode levar de 1 a 10 min.
Pare em success ou fail. Com callBackUrl, você nem precisa consultar.

Callback

Com callBackUrl na criação, mandamos um POST em JSON para essa URL quando a tarefa termina, com sucesso ou com falha. O data é o mesmo do recordInfo.

Item	Como é
Sucesso	`code: 200`
Falha	`code: 501` (o valor já foi devolvido)
Prazo para responder	10 s. Responda 2xx logo e processe depois.
Repetições	Até 3 tentativas no total: a primeira quando a tarefa termina e as outras nos minutos seguintes, se a sua URL não responder 2xx.
Endereço	Só HTTPS público. Não seguimos redirecionamento.

{
  "code": 200,
  "msg": "Task completed successfully.",
  "data": {
    "taskId": "3f9c2a7be1d84c0f9a6b5e21c7d04a18",
    "model": "nano-banana-2",
    "state": "success",
    "param": "{\"model\":\"nano-banana-2\",\"input\":\"{\\\"prompt\\\":\\\"...\\\"}\"}",
    "resultJson": "{\"resultUrls\":[\"https://.../resultados/3f9c2a7be1d84c0f9a6b5e21c7d04a18/0.png\"]}",
    "failCode": "",
    "failMsg": "",
    "costTime": 21,
    "completeTime": 1793660021000,
    "createTime": 1793660000000,
    "updateTime": 1793660021000,
    "creditsConsumed": 9.26
  }
}

O corpo do callback não é assinado. Antes de liberar algo importante (entregar ao cliente, cobrar), confirme com GET /api/v1/jobs/recordInfo usando a sua chave.

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/hubroque", async (req, res) => {
  res.json({ ok: true }); // responda rápido (até 10 s)

  const taskId = req.body?.data?.taskId;
  if (!taskId) return;
  // O corpo não é assinado: confirme na API antes de liberar algo importante.
  const r = await fetch(`https://api.hubroque.com.br/api/v1/jobs/recordInfo?taskId=${taskId}`, {
    headers: { Authorization: `Bearer ${process.env.HUBROQUE_API_KEY}` },
  });
  const s = await r.json();
  if (s.code === 200 && s.data.state === "success") {
    const { resultUrls } = JSON.parse(s.data.resultJson);
    console.log("Pronto:", resultUrls);
  }
});

app.listen(3000);

Exemplos completos

Cria a tarefa, consulta até terminar e mostra os links. Troque a chave e rode.

const BASE = "https://api.hubroque.com.br/api/v1";
const headers = {
  Authorization: "Bearer hr_SUA_CHAVE",
  "Content-Type": "application/json",
};
const espera = (ms) => new Promise((ok) => setTimeout(ok, ms));

const r = await fetch(`${BASE}/jobs/createTask`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "model": "nano-banana-2",
    "input": {
      "prompt": "Tênis branco em fundo azul, luz de estúdio, foto de produto",
      "resolution": "1K"
    }
  }),
});
const j = await r.json();
if (j.code !== 200) throw new Error(`${j.code}: ${j.msg}`);

for (;;) {
  await espera(4000);
  const s = await (
    await fetch(`${BASE}/jobs/recordInfo?taskId=${j.data.taskId}`, { headers })
  ).json();
  if (s.code !== 200) throw new Error(`${s.code}: ${s.msg}`);
  if (s.data.state === "success") {
    console.log(JSON.parse(s.data.resultJson).resultUrls);
    break;
  }
  if (s.data.state === "fail") throw new Error(`${s.data.failCode}: ${s.data.failMsg}`);
}

Enviar arquivo

Modelos que recebem imagem, vídeo ou áudio pedem um link público. Se o arquivo está no seu computador, envie por uma destas rotas e use o downloadUrl da resposta no input.

Rota	Formato	Campos	Limite
`POST /api/file-stream-upload`	multipart	`file`, `uploadPath`, `fileName`	4,5 MB por pedido
`POST /api/file-base64-upload`	JSON	`base64Data`, `uploadPath`, `fileName`	4,5 MB por pedido (o base64 aumenta ~33%)
`POST /api/file-url-upload`	JSON	`fileUrl`, `uploadPath`, `fileName`	até 100 MB

Aceita imagem, vídeo e áudio. O tipo é conferido pelo conteúdo do arquivo.
uploadPath e fileName são aceitos por compatibilidade. O nome final é gerado por nós.
Arquivo maior que 4,5 MB: deixe num link público e use o envio por URL.
Limite de 300 envios por hora por conta.
Arquivos enviados ficam 3 dias e depois são apagados.

curl -X POST "https://api.hubroque.com.br/api/file-stream-upload" \
  -H "Authorization: Bearer hr_SUA_CHAVE" \
  -F "file=@/caminho/foto.jpg" \
  -F "uploadPath=meu-app/fotos" \
  -F "fileName=foto.jpg"

Resposta (igual nas três rotas)

{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "fileName": "foto.jpg",
    "filePath": "...",
    "downloadUrl": "https://.../entradas/.../foto.jpg",
    "fileSize": 154832,
    "mimeType": "image/jpeg",
    "uploadedAt": "2026-11-02T12:00:00.000Z"
  }
}

Link de download

POST/api/v1/common/download-url

Existe por compatibilidade. Os links do HubRoque já baixam direto, então a resposta devolve o mesmo link. Só aceita links de resultados da sua conta.

cURL

curl -X POST "https://api.hubroque.com.br/api/v1/common/download-url" \
  -H "Authorization: Bearer hr_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://.../resultados/3f9c.../0.png"}'

Resposta

{ "code": 200, "msg": "success", "data": "https://.../resultados/3f9c.../0.png" }

Prazos dos arquivos

Arquivo	Fica guardado
Gerados (resultados)	30 dias
Enviados por você (uploads)	3 dias

Depois do prazo, o link para de funcionar. Baixe e guarde no seu próprio armazenamento o que quiser manter.

Saldo

GET/api/v1/chat/credit

cURL

curl "https://api.hubroque.com.br/api/v1/chat/credit" \
  -H "Authorization: Bearer hr_SUA_CHAVE"

Resposta

{"code":200,"msg":"success","data":729.94}

data é o saldo disponível em créditos equivalentes. Para ver em reais: data × 0.0648. No exemplo acima, o saldo é de R$ 47,30.

Catálogo de modelos

GET/api/v1/modelos

Lista os modelos ativos com campos e preços. Não precisa de chave. Os preços vêm em centavos de real (centavos: 60 = R$ 0,60).

cURL

curl "https://api.hubroque.com.br/api/v1/modelos"

Resposta (resumida)

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "nano-banana-2",
      "slug": "nano-banana-2",
      "nome": "Nano Banana 2",
      "provedor": "Google",
      "tarefas": ["texto-para-imagem", "editar-imagem"],
      "saida": "imagem",
      "descricao": "...",
      "campos": [ { "nome": "prompt", "tipo": "string", "obrigatorio": true } ],
      "tabela": [ { "rotulo": "1K", "centavos": 60 } ],
      "a_partir_de_centavos": 60,
      "destaque": true,
      "capa_url": null
    }
  ]
}

Erros

O código vai no campo code do corpo. A mensagem (msg) vem em português.

code	Quando acontece	Cobrou?	O que fazer
200	Deu certo.	—	—
401	Chave ausente, errada ou revogada. Conta bloqueada.	Não	Confira o cabeçalho `Authorization`.
402	Saldo insuficiente.	Não	Adicione saldo no painel.
422	Parâmetro inválido, opção sem preço, modelo inexistente ou pausado, ou tarefa que não existe ou não é sua.	Não	Leia o `msg` e corrija.
429	Muitos pedidos, muitas tarefas ao mesmo tempo ou limite diário de gasto atingido.	Não	Espere e tente de novo. O limite diário muda no painel.
455	Sistema em manutenção ou com muita demanda.	Não	Tente de novo em alguns minutos.
500	Erro nosso.	Talvez	Na criação, confira o histórico antes de repetir. Se falhar, o valor volta.
501	A geração falhou.	Não (devolvido)	Ajuste o pedido e tente de novo.
505	Recurso não disponível (ex.: 4K e extensão no formato Veo antigo).	Não	Use outra opção.

Outros códigos 4xx (como 400 e 404) também são recusa definitiva, sem cobrança.
429 e 455 só aparecem quando a tarefa com certeza não foi criada: pode repetir.

Limites

Limite	Valor
Tarefas ao mesmo tempo, por conta	20
Tarefas criadas por minuto, por conta	60
Gasto por dia, por conta (padrão)	R$ 1.000,00 (ajustável no painel)
Gasto por dia, por chave	Opcional, definido em cada chave
Envio de arquivo	4,5 MB por pedido; até 100 MB por URL; 300 envios por hora

Passou do limite: o pedido volta com 429 e nada é cobrado.

Claude e ChatGPT (MCP)

O HubRoque também funciona como servidor MCP: dá para usar dentro do Claude, do ChatGPT e do Claude Code, pedindo em português. As ferramentas são listar_modelos, ver_saldo, gerar e consultar_tarefa. Cada geração desconta do mesmo saldo, pelo mesmo preço.

Como	Endereço
Com cabeçalho (Claude Code, apps)	`https://api.hubroque.com.br/api/mcp`
Link do conector (Claude, ChatGPT)	Gerado no painel, em Conectar.

Claude Code

claude mcp add --transport http hubroque https://api.hubroque.com.br/api/mcp \
  --header "Authorization: Bearer hr_SUA_CHAVE"

Passo a passo para Claude e ChatGPT

Apps antigos (rota do Veo)

Apps que usam o formato antigo do Veo (/api/v1/veo/generate e /api/v1/veo/record-info) continuam funcionando. Para código novo, use as rotas acima.

Ver a rota antiga do Veo