Skip to content
Closed
Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -307,7 +307,7 @@ OpenClaude supports multiple providers, but behavior is not identical across all
- Tool quality depends heavily on the selected model
- Smaller local models can struggle with long multi-step tool flows
- Some providers impose lower output caps than the CLI defaults, and OpenClaude adapts where possible
- AI/ML API uses the OpenAI-compatible route, defaults to `gpt-4o`, and only surfaces chat-capable models from its public catalog
- AI/ML API uses the OpenAI-compatible route, defaults to `anthropic/claude-sonnet-5`, supports passwordless guided onboarding/top-up, and only surfaces chat-capable models from its public catalog
- Gitlawb Opengateway is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. It uses one OpenAI-compatible base URL; switch between `mimo-*` and `google/gemini-3.1-flash-lite-preview` with `/model`, and do not pin the base URL to `/v1/xiaomi-mimo`.
- Z.AI GLM Coding Plan uses `https://api.z.ai/api/coding/paas/v4` with `glm-5.2` by default. Use `glm-5.2?reasoning=high` for enhanced reasoning, `glm-5.2?reasoning=xhigh` to request Z.AI `reasoning_effort=max`, or `glm-5.2?thinking=disabled` for faster direct answers.
- Xiaomi MiMo uses `api-key` header auth on the direct OpenAI-compatible route and currently does not support `/usage` reporting in OpenClaude
Expand Down
44 changes: 27 additions & 17 deletions docs/aimlapi-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,41 +4,49 @@ OpenClaude connects to [AI/ML API](https://aimlapi.com) through its OpenAI-compa

## Overview

AI/ML API is an aggregating gateway that exposes many chat models behind a single OpenAI-compatible API. OpenClaude ships a first-class `AI/ML API` provider preset: it stores credentials under `AIMLAPI_API_KEY`, sends the OpenClaude attribution headers, and discovers chat-capable models from the public `/models` catalog. It defaults to `gpt-4o`.
AI/ML API is an aggregating gateway that exposes many chat models behind a single OpenAI-compatible API. OpenClaude ships a first-class `AI/ML API` provider preset: it uses `AIMLAPI_API_KEY`, sends the OpenClaude attribution headers, and discovers chat-capable models from the public `/models` catalog. It defaults to `anthropic/claude-sonnet-5`.

## Prerequisites

None. You don't need to visit <https://aimlapi.com> first — the guided top-up flow below can create an AI/ML API account and issue a key for you. If you already have a key from the dashboard, you can paste it directly instead.
None. You do not need to visit <https://aimlapi.com> first - the guided top-up flow can create an account and issue a key. If you already have a dashboard key or set `AIMLAPI_API_KEY`, OpenClaude can use that credential instead.

## Option 1 — Interactive (`/provider`)
## Option 1 - Interactive (`/provider`)

1. Start OpenClaude and run `/provider`.
2. Choose **AI/ML API**, then confirm the default model (Step 1 of 2).
3. Step 2 of 2 — choose how to get an API key:
- **Top up and get API key** — enter your AI/ML API email and password (an account is created automatically if you don't have one yet), pick a top-up amount ($20–$10,000) and payment method (card or crypto), complete payment in the browser, and OpenClaude saves the issued key for you.
- **Enter existing API key** — paste a key you already have from the AI/ML API dashboard.
2. Choose **aimlapi.com**.
3. If aimlapi.com is already configured, choose one of:
- **Continue with your saved API key** - validate the saved key or `AIMLAPI_API_KEY`, check its balance, optionally top up a low balance, then choose a model.
- **Set up a new key or switch account** - enter the new-user or existing-key flow.
4. Otherwise choose how to get an API key:
- **I am a new user** - enter your email. OpenClaude creates a passwordless account, lets you pick a top-up amount and automatic top-up preference, opens card checkout, then saves the issued key.
- **I already have aimlapi.com key** - paste a key from the dashboard. OpenClaude validates it, checks its balance, and offers an optional API-key top-up when the balance is low.

Either way, the base URL (`https://api.aimlapi.com/v1`) and default model (`gpt-4o`) are filled in automatically.
For an email that already has an account, AI/ML API sends a 6-digit sign-in code. OpenClaude creates a new API key for that account, checks its balance, and only offers checkout when the balance is low. You can top up or save the key and skip funding for now.

Switch models any time with `/model` — only chat-capable models from the AI/ML API catalog are listed.
When `AIMLAPI_API_KEY` supplies the credential, OpenClaude uses its runtime value for validation and balance checks but saves an empty credential in the provider profile. The literal environment value is not copied into configuration.

## Option 2 — CLI (`openclaude aimlapi topup`)
Checkout progress is retained while the provider flow remains open. Retrying an ambiguous payment or exchange failure resumes the original partner session instead of creating a second checkout.

Run the same guided top-up flow non-interactively:
The base URL (`https://api.aimlapi.com/v1`) and default model (`anthropic/claude-sonnet-5`) are filled in automatically. Switch models any time with `/model`; only chat-capable models from the AI/ML API catalog are listed.

## Option 2 - CLI (`openclaude aimlapi topup`)

Run the guided account top-up flow from the CLI:

```bash
openclaude aimlapi topup --email you@example.com --amount 25 --method card
openclaude aimlapi topup --email you@example.com --amount 25
```

- Credentials: pass `--email` (or set `AIMLAPI_EMAIL`) and set `AIMLAPI_PASSWORD`; if either is missing you're prompted interactively (password entry is hidden).
- Pass `--email` (or set `AIMLAPI_EMAIL`). Existing accounts also need the emailed `--code` (or `AIMLAPI_CODE`); interactive terminals prompt for missing values.
- `--amount`: top-up amount in USD (min 20, max 10000; defaults to 25).
- `--method`: `card` (Stripe, default) or `crypto` (NOWPayments).
- `--model`: default model id written into the provider profile (defaults to `gpt-4o`).
- Checkout always uses card payment; there is no separate payment-method step.
- `--auto-top-up`: enroll the account in automatic top-up at checkout.
- `--model`: default model id written into the provider profile (defaults to `anthropic/claude-sonnet-5`).
- `--no-open`: print the payment URL instead of auto-opening a browser.

The issued key is written into OpenClaude's provider profile automatically once payment clears.

## Option 3 — Environment variables
## Option 3 - Environment variables

Setting `AIMLAPI_API_KEY` alone is enough; OpenClaude auto-detects the AI/ML API route:

Expand All @@ -52,7 +60,7 @@ To configure the OpenAI-compatible route explicitly:
export CLAUDE_CODE_USE_OPENAI=1
export AIMLAPI_API_KEY="your-aimlapi-key"
export OPENAI_BASE_URL="https://api.aimlapi.com/v1"
export OPENAI_MODEL="gpt-4o"
export OPENAI_MODEL="anthropic/claude-sonnet-5"
```

`OPENAI_API_KEY` also works as a fallback credential for the route.
Expand All @@ -67,4 +75,6 @@ export OPENAI_MODEL="gpt-4o"

- Model discovery uses the public, unauthenticated `GET /models` endpoint and surfaces only chat-completions models; image, audio, embeddings, and other modalities are intentionally not routed through the coding workflow.
- Requests carry `X-AIMLAPI-Integration-*` attribution headers (owner/repo/version) plus the `HTTP-Referer: OpenClaude` and `X-Title: OpenClaude` headers that AI/ML API uses to attribute integration traffic.
- `AIMLAPI_AUTH_URL`, `AIMLAPI_APP_URL`, `AIMLAPI_PAY_URL`, `AIMLAPI_INFERENCE_URL`, and `AIMLAPI_VERIFICATION_BASE_URL` can point the complete flow at another environment. `AIMLAPI_RETURN_URL` overrides only the browser landing page.
- Checkout success is detected by polling. The browser return target is an HTTPS page; OpenClaude does not install a custom URL-scheme handler.
- Usage (`/usage`) reporting is not supported for this provider.
49 changes: 49 additions & 0 deletions src/cli/aimlapiCommand.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import { expect, mock, test } from 'bun:test'
import { Command as CommanderCommand } from '@commander-js/extra-typings'

import { registerAimlapiCommand } from './aimlapiCommand.js'

test('aimlapi topup forwards the passwordless CLI contract', async () => {
const handler = mock(async () => {})
const program = new CommanderCommand().exitOverride()
registerAimlapiCommand(program, async () => handler)

await program.parseAsync([
'node',
'openclaude',
'aimlapi',
'topup',
'--email',
'user@example.com',
'--code',
'123456',
'--auto-top-up',
'--no-open',
])

expect(handler).toHaveBeenCalledWith({
email: 'user@example.com',
code: '123456',
amountUsd: undefined,
autoTopUp: true,
model: 'anthropic/claude-sonnet-5',
partnerId: undefined,
noOpen: true,
})
})

test('aimlapi topup rejects the removed method option', async () => {
const program = new CommanderCommand().exitOverride()
registerAimlapiCommand(program, async () => async () => {})

await expect(
program.parseAsync([
'node',
'openclaude',
'aimlapi',
'topup',
'--method',
'card',
]),
).rejects.toMatchObject({ code: 'commander.unknownOption' })
})
58 changes: 58 additions & 0 deletions src/cli/aimlapiCommand.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import { Command as CommanderCommand } from '@commander-js/extra-typings'

import {
DEFAULT_MODEL,
MAX_AMOUNT_USD_MINOR,
MIN_AMOUNT_USD_MINOR,
} from '../integrations/aimlapi/config.js'
import type { AimlapiTopupOptions } from '../integrations/aimlapi/topup.js'

type AimlapiTopupHandler = (options: AimlapiTopupOptions) => Promise<void>
type LoadAimlapiTopupHandler = () => Promise<AimlapiTopupHandler>

const loadAimlapiTopupHandler: LoadAimlapiTopupHandler = async () => {
const { aimlapiTopup } = await import('./handlers/aimlapi.js')
return aimlapiTopup
}

export function registerAimlapiCommand(
program: CommanderCommand,
loadHandler: LoadAimlapiTopupHandler = loadAimlapiTopupHandler,
): CommanderCommand {
const aimlapi = program
.command('aimlapi')
.description('AI/ML API (aimlapi.com) — top up balance and configure the provider')
aimlapi
.command('topup')
.description(
'Use passwordless sign-in, open AI/ML API top-up, then configure OpenClaude',
)
.option('--email <email>', 'AI/ML API account email (or AIMLAPI_EMAIL env)')
.option('--code <code>', '6-digit code for an existing account (or AIMLAPI_CODE env)')
.option(
'--amount <usd>',
`Top-up amount in USD (min ${MIN_AMOUNT_USD_MINOR / 100}, max ${MAX_AMOUNT_USD_MINOR / 100})`,
)
.option('--auto-top-up', 'Enable automatic top-up at checkout')
.option(
'--model <model>',
'Default model id written into the provider profile',
DEFAULT_MODEL,
)
.option('--partner-id <id>', 'Partner id for rebate attribution (part_...)')
.option('--no-open', 'Do not auto-open the browser; print the payment URL instead')
.action(async opts => {
const handler = await loadHandler()
await handler({
email: opts.email,
code: opts.code,
amountUsd: opts.amount,
autoTopUp: opts.autoTopUp,
model: opts.model,
partnerId: opts.partnerId,
noOpen: opts.open === false,
})
})

return aimlapi
}
9 changes: 6 additions & 3 deletions src/cli/handlers/aimlapi.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/* eslint-disable custom-rules/no-process-exit -- CLI subcommand handler intentionally exits */

import chalk from 'chalk'
import { redactSensitiveInfo } from '../../utils/redaction.js'

import { AimlapiApiError } from '../../integrations/aimlapi/client.js'
import {
Expand All @@ -13,12 +14,14 @@ export async function aimlapiTopup(options: AimlapiTopupOptions): Promise<void>
await runAimlapiTopup(options)
} catch (error) {
if (error instanceof AimlapiApiError) {
console.error(chalk.red(`\n ✗ ${error.message}`))
console.error(chalk.red(`\n ✗ ${redactSensitiveInfo(error.message)}`))
if (error.body) {
console.error(chalk.dim(` ${error.body}`))
console.error(chalk.dim(` ${redactSensitiveInfo(error.body)}`))
}
} else {
const message = error instanceof Error ? error.message : String(error)
const message = redactSensitiveInfo(
error instanceof Error ? error.message : String(error),
)
console.error(chalk.red(`\n ✗ ${message}`))
}
process.exit(1)
Expand Down
2 changes: 1 addition & 1 deletion src/components/ConsoleOAuthFlow.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ test('third-party provider branch opens the first-run provider manager', async (
expect(output).toContain('Set up provider')
// Keep the sentinels near the top of the preset list so adding another
// provider does not push the assertion outside the 13-row test frame.
expect(output).toContain('AI/ML API')
expect(output).toContain('aimlapi.com')
expect(output).toContain('Anthropic')
expect(output).toContain('Azure OpenAI')
expect(output).toContain('DeepSeek')
Expand Down
Loading
Loading