Ir para a documentação
RubyCLIDocumentaçãoEntrar no painel
openai-compatibleSSEv1

Ruby · API e CLI

Documentação da API e CLI

Use os modelos Ruby no terminal com o Claude Code, com nossa CLI ou em aplicações compatíveis com a API da OpenAI. O consumo é descontado do seu saldo conforme o uso.

Nesta página

01 · Quickstart

Sua primeira chamada

Aponte o SDK para a base URL Ruby e use uma chave de API ativa. Se seu código já usa OpenAI, normalmente basta trocar esses dois valores.

Base URL

https://app.rubycli.cloud/v1
  1. 1Crie uma chave na aba Chaves de API.
  2. 2Escolha um ID na lista de modelos abaixo.
  3. 3Envie a chamada. Entrada e saída consomem Ruby Units do seu saldo.
curl "https://app.rubycli.cloud/v1/chat/completions" \  -H "Authorization: Bearer $RUBY_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "ID_DO_MODELO",    "messages": [      {"role": "user", "content": "Olá!"}    ]  }'

02 · Claude Code

Seu terminal, conectado à Ruby

O instalador RubyCLI prepara o Claude Code oficial e conecta os modelos da sua conta. Também reconhece o aplicativo Claude já instalado para configurar o Desktop e o Cowork. Escolha seu sistema para começar.

InstaladorRubyCLI
Execute no PowerShell
irm https://app.rubycli.cloud/install.ps1 | iex
Prefere consultar o arquivo?Baixar install.ps1
  1. 1

    Informe sua chave

    Crie uma chave em Chaves de API e cole quando o instalador solicitar. O valor fica oculto durante a digitação.

  2. 2

    Escolha um modelo

    Selecione um dos modelos liberados para sua chave. O instalador salva a conexão e preserva suas outras configurações.

  3. 3

    Abra seu projeto

    Na pasta em que deseja trabalhar, execute claude. Acompanhe o consumo em Ruby Units no Dashboard.

Requer PowerShell 5.1 ou superior. Abra um novo terminal após a instalação.

Se o Claude Code já estiver instalado, ele será aproveitado. A configuração anterior recebe uma cópia de segurança. Execute o instalador novamente quando quiser trocar a chave ou o modelo.

Claude Desktop e Cowork

O aplicativo precisa estar instalado no computador. Quando a conexão Ruby for aplicada, feche e abra o Claude para usar a nova configuração no Desktop e no Cowork.

Se você já entrou com uma conta pessoal da Anthropic, o instalador mantém essa conexão. Para escolher a Ruby no lugar dela, execute os comandos abaixo no PowerShell:

Conectar o aplicativo à Ruby · Windows
$env:RUBY_DESKTOP = "1"irm https://app.rubycli.cloud/install.ps1 | iex

A CLI Ruby continua disponível pelo comando ruby, com a instalação própria descrita a seguir.

03 · Ruby CLI

Um agente direto no terminal

A Ruby também tem seu próprio agente de programação: a CLI Ruby, iniciada pelo comando ruby. Instale o pacote abaixo, escolha um modelo e descreva o que quer fazer no seu projeto. As chamadas consomem créditos conforme os tokens processados.

Requer Node.js 20.6 ou superior. Crie uma chave em Chaves de API e cole o valor completo no comando. Mantenha sua chave privada.

Ver pacote no npm
Terminal · instalação e configuração
npm install -g @rubyclii/cliruby config --api-key SUA_CHAVE_COMPLETAruby config --model gpt-6-lunaruby

Substitua SUA_CHAVE_COMPLETA pela chave copiada no painel. A configuração fica salva localmente no seu usuário.

04 · Ruby Desktop

Agentes de código em um aplicativo desktop

O Ruby Desktop é o nosso Harness Desktop para trabalhar com agentes de programação conectado ao provider Ruby. A documentação verifica a release estável mais recente e mostra os instaladores e comandos disponíveis para cada sistema.

Antes de usar: crie uma chave de API Ruby no painel e configure essa chave no Ruby Desktop para autenticar o provider Ruby. O aplicativo não usa a senha da sua conta; sem uma chave válida, os modelos não funcionarão. O consumo será descontado do seu saldo em RU.

Instaladores Ruby Desktop

A documentação verifica a release estável mais recente no GitHub e exibe os arquivos disponíveis em cada sistema.

Buscando a versão e os arquivos no GitHub…

05 · Protocolos e Codex

Uma conta, os formatos dos seus agentes

A Ruby aceita os formatos nativos Anthropic Messages e OpenAI Responses. Crie uma chave de API, escolha um ID liberado para sua conta e configure a base URL correspondente ao cliente.

Claude Code

Anthropic Messages · streaming e ferramentas do cliente

https://app.rubycli.cloud/anthropic

O instalador acima usa essa base e configura as ferramentas locais do Claude. O SDK acrescenta /v1/messages e envia anthropic-version.

Codex CLI e extensão de IDE

OpenAI Responses · streaming e ferramentas function executadas pelo cliente

https://app.rubycli.cloud/v1

O Codex usa /responses, com SSE e funções locais. O auxiliar valida sua chave e abre uma sessão Ruby, preservando sua configuração atual.

Compatibilidade: envie o histórico completo em cada chamada. Use store: false no Responses. Respostas persistentes, conversas por ID, background, WebSocket e ferramentas hospedadas pelos provedores não estão disponíveis. O instalador desativa o thinking estendido do Claude; funções locais dependem do suporte do modelo.
curl "https://app.rubycli.cloud/v1/responses" \  -H "Authorization: Bearer $RUBY_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "model": "ID_DO_MODELO",  "input": "Explique o que este projeto faz.",  "max_output_tokens": 256,  "store": false}'

06 · Autenticação

Uma chave por projeto

Envie a chave no cabeçalho Authorization: Bearer. Guarde-a no servidor ou em variável de ambiente; nunca a coloque no código público do navegador ou no Git.

A chave completa aparece uma vezRevogue e crie outra quando precisar

# .env — mantenha fora do Git

RUBY_API_KEY=sua-chave-ruby

Authorization: Bearer $RUBY_API_KEY

07 · Modelos

O catálogo liberado para sua conta

Use o valor de id exatamente como aparece no campo model.

GET /v1/models

Entre no painel para ver o catálogo da sua conta ou consulte os modelos pela API usando sua chave.

GET /v1/models

08 · Chat completions

Converse com um modelo

A Ruby oferece o formato de chat compatível com OpenAI. Envie uma lista de mensagens e o ID exato do catálogo; a resposta segue o formato padrão de chat completion.

POSThttps://app.rubycli.cloud/v1/chat/completions
model

ID do modelo retornado por /v1/models.

messages

Mensagens no formato OpenAI, com papel e conteúdo.

stream

Opcional. Ative true para receber a resposta aos poucos.

09 · Geração e edição de imagens

Crie ou edite imagens com sua chave Ruby

A API de imagens usa sua chave Ruby no cabeçalho Bearer. Primeiro consulte os modelos disponíveis e as variantes com preço configurado; depois cote e envie a geração ou edição. Use o ID exato do modelo retornado pelo catálogo.

1. Listar modelos e variantes

GET /v1/images/models
curl https://app.rubycli.cloud/v1/images/models -H 'Authorization: Bearer $RUBY_API_KEY'

A resposta contém id, name, supports_edits e variants (combinações de tamanho e qualidade com preço disponível). Só use edição quando supports_edits for true.

{
  "object": "list",
  "data": [
    {
      "id": "qwen/qwen-image-2.1-turbo",
      "name": "Qwen Image 2.1 Turbo",
      "supports_edits": true,
      "variants": [
        "1024x1024|standard"
      ]
    }
  ]
}

2. Cotar antes de enviar

POST /v1/images/quote

Envie JSON. Para edição, passe referenceCount com a quantidade de imagens de referência para estimar o custo corretamente.

curl --request POST https://app.rubycli.cloud/v1/images/quote --header 'Authorization: Bearer $RUBY_API_KEY' --header 'Content-Type: application/json' --data '{"model":"qwen/qwen-image-2.1-turbo","size":"1024x1024","quality":"standard","n":1,"referenceCount":1}'
{
  "model": "qwen/qwen-image-2.1-turbo",
  "size": "1024x1024",
  "quality": "standard",
  "count": 1,
  "referenceCount": 1,
  "estimatedCredits": "...",
  "minEstimatedCredits": "...",
  "maxEstimatedCredits": "..."
}

estimatedCredits estima a primeira rota; minEstimatedCredits e maxEstimatedCredits mostram a faixa entre rotas ativas. n e referenceCount aceitam de 1 a 4 e de 0 a 4, respectivamente.

3A. Gerar imagem

POST /v1/images/generations

Envie JSON com model e prompt. size e quality devem corresponder a uma variante do catálogo.

curl --request POST https://app.rubycli.cloud/v1/images/generations --header 'Authorization: Bearer $RUBY_API_KEY' --header 'Content-Type: application/json' --data '{"model":"qwen/qwen-image-2.1-turbo","prompt":"Uma paisagem ao pôr do sol","size":"1024x1024","quality":"standard","n":1}'

3B. Editar com arquivo de referência

POST /v1/images/edits

Use multipart/form-data: o arquivo vai no campo image; os demais campos são texto. O endpoint aceita PNG, JPEG e WebP, com arquivo de até 12 MB. Não defina o Content-Type manualmente no cURL.

curl --request POST https://app.rubycli.cloud/v1/images/edits --header 'Authorization: Bearer $RUBY_API_KEY' --form 'model=qwen/qwen-image-2.1-turbo' --form 'prompt=Remova o fundo e coloque a imagem em um jardim' --form 'image=@referencia.png' --form 'size=1024x1024' --form 'quality=standard' --form 'n=1'

Uma referência é obrigatória neste endpoint. Para clientes que enviam JSON, use input_references com até quatro URLs HTTPS ou data URLs. Cada item tem o formato:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,..."
  }
}

Inclua essa lista no mesmo JSON de model e prompt. A compatibilidade com várias referências depende do modelo e da rota ativa.

Campos e limites

  • model: obrigatório; ID exato de /v1/images/models.
  • prompt: obrigatório, até 12.000 caracteres.
  • size: padrão 1024x1024; precisa ter preço na variante.
  • quality: padrão standard; precisa ter preço na variante.
  • n: quantidade de imagens, de 1 a 4.
  • response_format: somente b64_json; URLs persistentes não são fornecidas.

Resposta e erros

Sucesso: data[] contém b64_json, media_type e, quando disponível, revised_prompt. usage.credits informa o débito final em RU. Decodifique o base64 para salvar a imagem.

Erros comuns: 400 parâmetros inválidos ou modelo sem edição; 402 saldo insuficiente; 404 modelo não encontrado; 503 sem rota/preço configurado. Se o fornecedor falhar, a reserva é liberada e nenhum crédito é cobrado.

Privacidade: as imagens retornam em base64 para você baixar; a Ruby não as armazena. Prompts e conteúdo das imagens também não são incluídos nos logs, que registram consumo e metadados da requisição.

10 · Streaming

Respostas em tempo real

Defina stream: true. Chat Completions envia deltas e termina com [DONE]; Responses usa eventos como response.output_text.delta e response.completed. Anthropic Messages usa content_block_delta e message_stop.

stream: true,

stream_options: { include_usage: true }

11 · Créditos e consumo

Acompanhe o uso do seu saldo

Cada resposta desconta Ruby Units de acordo com o modelo e os tokens de entrada e saída informados pelo provedor. Modelos que oferecem cache podem ter uma tarifa própria para tokens em cache. Veja o saldo e o histórico no Dashboard.