GPU Rental 6 min de leitura

Referencia da API

Gerencie as suas instancias GPU de forma programatica. Aprenda a autenticar, criar instancias, verificar o estado e muito mais atraves da API da GPUnex.

Obter a Sua Chave de API

A API da GPUnex permite-lhe gerir instancias GPU, verificar saldos e automatizar os seus fluxos de trabalho sem utilizar o painel web. Antes de efetuar qualquer pedido a API, precisa de gerar uma chave de API.

Inicie sessao na sua conta GPUnex e navegue ate a sua pagina de Perfil ou ao painel de definicoes do Dashboard.
Abra a seccao de Chaves de API. Procure o separador ou cartao Chaves de API nas definicoes da sua conta.
Clique em “Criar Nova Chave de API”. Ser-lhe-a pedido que de um nome descritivo a chave. Escolha algo significativo que identifique a finalidade da chave — por exemplo, “Servidor de Producao”, “Pipeline CI/CD” ou “Desenvolvimento Local”. Isto facilita a gestao de multiplas chaves posteriormente.
Copie a sua chave de API imediatamente. Apos a geracao da chave, esta sera apresentada apenas uma vez. Copie-a e armazene-a num local seguro, como um gestor de palavras-passe ou um cofre de segredos encriptado. Nao podera visualizar a chave completa novamente apos este passo.
Compreenda o ambito e a revogacao das chaves. Cada chave de API esta associada a sua conta e herda as permissoes da mesma. Pode criar multiplas chaves para diferentes aplicacoes ou ambientes. Se uma chave for comprometida ou ja nao for necessaria, pode revoga-la a qualquer momento na seccao de Chaves de API. A revogacao e imediata e permanente — todos os pedidos que utilizem essa chave serao rejeitados.

Autenticacao

Todos os pedidos a API da GPUnex devem incluir um cabecalho Authorization com a sua chave de API utilizando o esquema Bearer token.

Formato do cabecalho:

Authorization: Bearer YOUR_API_KEY

Terminal

$

Se a chave de API estiver ausente, invalida ou revogada, a API retornara uma resposta 401 Unauthorized:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key. Please check your Authorization header."
}

Certifique-se de que a sua chave esta incluida em todos os pedidos. A API nao suporta autenticacao baseada em sessoes ou cookies.

Endpoints Principais

A API da GPUnex esta organizada em torno de recursos RESTful. Todos os endpoints utilizam o URL base https://api.gpunex.com/v1. Abaixo encontra um resumo dos endpoints principais disponiveis.

Metodo	Endpoint	Descricao
GET	`/v1/instances`	Lista todas as suas instancias ativas e recentes. Retorna um array de objetos de instancia com o estado atual, modelo GPU e detalhes de configuracao.
POST	`/v1/instances`	Cria uma nova instancia GPU. Requer um corpo JSON especificando o modelo GPU, framework e regiao. Os custos sao deduzidos do seu saldo USDC.
GET	`/v1/instances/:id`	Obtem informacoes detalhadas sobre uma instancia especifica pelo seu ID unico. Inclui detalhes de conexao SSH, metricas de execucao e informacoes de faturacao.
DELETE	`/v1/instances/:id`	Termina uma instancia em execucao. A instancia sera parada e deixara de ser cobrada. Quaisquer dados nao guardados na instancia serao perdidos.
GET	`/v1/gpu-models`	Lista todos os modelos GPU atualmente disponiveis no marketplace. Inclui precos, VRAM, disponibilidade por regiao e frameworks suportados.
GET	`/v1/balance`	Verifica o seu saldo atual da carteira USDC e um resumo das transacoes recentes.

Todas as respostas sao devolvidas em formato JSON. Pedidos bem-sucedidos retornam um codigo de estado 200 OK para pedidos GET e um codigo de estado 201 Created para pedidos POST que criam recursos.

Exemplo: Criar uma Instancia

Para criar uma nova instancia GPU, envie um pedido POST para /v1/instances com um corpo JSON especificando a configuracao desejada.

Pedido:

Terminal

$

Parametros do corpo do pedido:

Parametro	Tipo	Obrigatorio	Descricao
`gpu_model`	string	Sim	O identificador do modelo GPU. Utilize `/v1/gpu-models` para ver as opcoes disponiveis (ex.: `H100_80GB`, `A100_80GB`, `L40S_48GB`, `L4_24GB`).
`framework`	string	Sim	O framework e versao pre-instalados (ex.: `pytorch-2.3`, `tensorflow-2.16`, `jax-0.4`).
`region`	string	Sim	A regiao do datacenter para a instancia (ex.: `us-east-1`, `eu-west-1`, `ap-southeast-1`).

Exemplo de resposta (201 Created):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "provisioning",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": null,
  "hourly_rate": "1.89",
  "currency": "USDC",
  "created_at": "2026-02-15T14:32:07Z"
}

A instancia tera inicialmente o estado provisioning. Assim que a GPU for alocada e o ambiente estiver pronto, o estado mudara para running e o campo ssh_command sera preenchido com a sua string de conexao. O provisionamento demora tipicamente entre 30 segundos e 2 minutos, dependendo da disponibilidade.

Exemplo: Verificar o Estado da Instancia

Apos criar uma instancia, pode verificar o seu estado atual a qualquer momento consultando o endpoint da instancia com o respetivo ID.

Pedido:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.gpunex.com/v1/instances/inst_7f3a9b2c4d1e

Exemplo de resposta (200 OK):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "running",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": "ssh [email protected] -p 2222",
  "ip_address": "203.0.113.42",
  "hourly_rate": "1.89",
  "currency": "USDC",
  "uptime_seconds": 3847,
  "total_cost": "2.02",
  "created_at": "2026-02-15T14:32:07Z",
  "started_at": "2026-02-15T14:33:15Z"
}

Valores de estado:

Estado	Significado
`provisioning`	A instancia esta a ser configurada. Os recursos GPU estao a ser alocados e o ambiente do framework esta a ser preparado.
`running`	A instancia esta ativa e pronta para utilizacao. O acesso SSH esta disponivel.
`stopping`	A instancia esta em processo de encerramento.
`terminated`	A instancia foi parada e ja nao incorre em custos.
`error`	Ocorreu um erro durante o provisionamento ou a execucao. Contacte o suporte se isto persistir.

Limites de Taxa e Boas Praticas

Limites de Taxa

A API da GPUnex aplica limites de taxa para garantir uma utilizacao justa e a estabilidade da plataforma. Os limites atuais sao:

Endpoints gerais: 120 pedidos por minuto por chave de API.
Criacao de instancias: 10 pedidos por minuto por chave de API.
Saldo e endpoints apenas de leitura: 300 pedidos por minuto por chave de API.

Se exceder o limite de taxa, a API retornara uma resposta 429 Too Many Requests com um cabecalho Retry-After indicando quantos segundos deve aguardar antes de tentar novamente.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 12 seconds.",
  "retry_after": 12
}

Boas Praticas

Siga estas diretrizes para manter a sua integracao segura e fiavel.

Nunca exponha chaves de API em codigo do lado do cliente. Nao incorpore a sua chave de API em JavaScript executado no navegador, codigo-fonte de aplicacoes moveis ou qualquer repositorio acessivel publicamente. As chaves de API devem ser utilizadas apenas em aplicacoes do lado do servidor, onde nao podem ser inspecionadas por utilizadores finais.

Importante

Nunca exponha a sua chave de API em codigo do lado do cliente, JavaScript do navegador ou repositorios publicos. As chaves de API devem ser utilizadas apenas em aplicacoes do lado do servidor.

Utilize variaveis de ambiente. Armazene a sua chave de API numa variavel de ambiente em vez de a codificar diretamente nos seus ficheiros de codigo-fonte. Por exemplo:
```
export GPUNEX_API_KEY="your_api_key_here"
```
Em seguida, referencie-a no seu codigo:
```
curl -H "Authorization: Bearer $GPUNEX_API_KEY" https://api.gpunex.com/v1/instances
```
Rotacione as chaves periodicamente. Como boa pratica de seguranca, gere uma nova chave de API a cada 90 dias e revogue a anterior. Isto limita o impacto caso uma chave seja inadvertidamente exposta.
Utilize chaves separadas para ambientes distintos. Crie chaves de API distintas para desenvolvimento, staging e producao. Desta forma, revogar uma chave nao afeta outros ambientes.

Dica

Utilize chaves de API separadas para desenvolvimento, staging e producao. Desta forma, revogar uma chave nao afeta outros ambientes.

Trate os erros de forma adequada. Verifique sempre os codigos de estado HTTP na sua aplicacao. Implemente logica de tentativa com backoff exponencial para respostas 429 e 5xx. Nao tente novamente erros 4xx alem do 429 — estes indicam um problema com o proprio pedido.
Monitorize a sua utilizacao. Acompanhe o volume de chamadas a API e os gastos com instancias. Utilize o endpoint /v1/balance para monitorizar programaticamente o seu saldo USDC e configure alertas caso este fique abaixo de um determinado limite.

Guias Relacionados

GPU Rental

Alugar e Implementar uma GPU

Como candidatar-se como locatario, escolher um modelo de GPU, implementar uma instancia e conectar-se via SSH no marketplace GPUnex.

7 min de leitura

Voltar à Base de Conhecimento