BeeMatra · Da foto ao material PBR contínuo

Autenticação

Todos os endpoints exigem um token Bearer no cabeçalho HTTP. Ausente ou inválido: HTTP 401:

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

As chaves de API são geradas em Conta → Chaves de API. A chave em texto claro é exibida apenas uma vez. Até 5 chaves ativas por conta, revogáveis a qualquer momento.

⚠️ A API aberta está disponível apenas para assinantes ativos. As tarefas só podem ser consultadas pelo criador (404 para as de outros).

Criar tarefa

POST https://beematra.net/api/v1/tasks

Envie uma foto de material para criar uma tarefa de geração. 1 crédito é debitado na aceitação; um task_id é retornado para consulta.

Parâmetros

Nome	Tipo	Descrição
image	file	Arquivo de imagem do material (formulário multipart), ≤20 MB, JPEG / PNG / WebP. Escolha entre image e image_url — image tem prioridade se ambos forem enviados
image_url	string	URL http(s) pública da imagem (corpo JSON), ≤20 MB

Exemplos de requisição

cURL · upload multipart direto (recomendado)

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -F "image=@/path/to/photo.jpg"

cURL · JSON com URL da imagem

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://example.com/photo.jpg"}'

Python

import requests resp = requests.post( "https://beematra.net/api/v1/tasks", headers={"Authorization": "Bearer bmk_xxxx"}, files={"image": open("photo.jpg", "rb")}, ) print(resp.json())

Resposta

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 0, "status_url": "https://beematra.net/api/v1/tasks/W20261020_170000_a1b2c3", "balance": 87 }

▸ 1 crédito debitado na aceitação; tarefas com falha são reembolsadas integralmente.
▸ O pré-processamento (rotação EXIF, normalização do lado maior em 1536 px) é automático.
▸ Apenas imagens completas — máscaras / recortes devem ser pré-processados pelo chamador antes do envio.

Consultar progresso

GET https://beematra.net/api/v1/tasks/{task_id}

GET https://beematra.net/api/v1/tasks/?task_id={task_id}

Consulte o status e o progresso da tarefa. Os formatos de caminho e consulta são equivalentes. Cabeçalho de autenticação obrigatório.

Resposta (em andamento)

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 45, "stage_label": "Generating textures…", "error": null, "note": null, "results": null }

Resposta (concluída — veja Texturas entregues para os campos)

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "succeeded", "progress": 100, "stage_label": "Completed", "error": null, "note": null, "results": { "albedo": "/uploads/derived/…/seamless_albedo.png", "normal": "/uploads/derived/…/normal.png", "roughness": "/uploads/derived/…/roughness.png", "height": "/uploads/derived/…/height.png", "ao": "/uploads/derived/…/ao.png", "preview_sphere": "/uploads/derived/…/preview_sphere.png", "preview_cube": "/uploads/derived/…/preview_cube.png" } }

Nome	Tipo	Descrição
status	string	running / succeeded / failed (tarefas com falha são reembolsadas automaticamente)
progress	integer	0-100
stage_label	string	Descrição legível da etapa atual (para exibição na UI)
error	string\|null	Motivo da falha quando status=failed
results	object\|null	Conjunto de URLs de texturas quando status=succeeded

▸ Sonde a cada 3-5 segundos; pare em succeeded/failed (limite 60/min).
▸ Você só pode consultar as suas próprias tarefas.

Consultar saldo

GET https://beematra.net/api/v1/balance

curl https://beematra.net/api/v1/balance \ -H "Authorization: Bearer bmk_xxxx"

Retorna o saldo de créditos da conta vinculada à chave.

Texturas entregues

Em caso de sucesso, results contém o conjunto de texturas PBR (2048 px seamless) e as pré-visualizações renderizadas:

Campo	Tipo	Descrição
albedo	string	Albedo seamless (cor base, sRGB)
normal	string	Normal map (OpenGL, Y+, linear)
roughness	string	Roughness map (linear)
height	string	Height / displacement map (linear)
ao	string	Mapa de oclusão ambiente (linear)
preview_sphere	string	Pré-visualização de renderização em esfera
preview_cube	string	Pré-visualização de renderização em cubo

Todas as URLs são baixadas diretamente, sem autenticação. O conteúdo é idêntico ao pacote "baixar tudo" do site (5 texturas + 2 pré-visualizações).

Códigos de erro

Erros retornam status HTTP diferente de 200 com {"ok": false, "error": "código", "message": "descrição"}

HTTP	error	Descrição
401	missing_or_bad_bearer	Cabeçalho Authorization ausente ou malformado
401	invalid_key	Chave de API inválida ou revogada
403	subscription_required	A API aberta requer uma assinatura ativa
400	no_image	Campo image ausente (ou erro de upload)
400	bad_type	Formato não suportado — apenas JPEG / PNG / WebP
400	too_large	Imagem excede o limite de 20 MB
400	bad_image_url	image_url não é um endereço http(s) público válido
400	image_download_failed	Falha no download de image_url (ou maior que 20 MB)
400	bad_task_id	task_id ausente ou malformado
404	task_not_found	Tarefa não encontrada, ou não pertence à conta desta chave
503	upstream_busy	Execution engine busy (usually near task completion) — simply poll again
429	rate_limited	Limite: 2 envios de tarefa / 60 consultas por minuto
429	queue_busy	Muitas tarefas na fila, tente novamente em breve

Regras de créditos

Aquisição	Novas contas recebem 3 créditos grátis. Assinaturas (Standard / Pro / Ultimate) entregam 100 / 500 / 1500 créditos por mês. O pacote turbo adiciona 50 créditos instantaneamente.
Consumo	Cada tarefa Beta custa 1 crédito, debitado na submissão; falhas são reembolsadas integralmente. Mesmo pool para o site e a API aberta.
Validade	Os créditos são válidos por 30 dias a partir da concessão; os expirados são limpos automaticamente. O consumo segue o lote que expira primeiro (FIFO).
Acompanhamento	Conta → Extrato de créditos: cada concessão, consumo, expiração e reembolso é registrado; o saldo sempre equivale à soma dos lotes não expirados.

Plataforma aberta