# Baidu AI Cloud

OpenAI-compatible LLM endpoint paid in **Units** via Fluxa TokenPay.
Drop-in for any OpenAI client — just swap the `baseURL`.

| | |
|---|---|
| **Endpoint** | `https://proxy-monetize.fluxapay.xyz/llm/baidu-ai-cloud/v1/chat/completions` |
| **Base URL** | `https://proxy-monetize.fluxapay.xyz/llm/baidu-ai-cloud/v1` |
| **Auth (humans)** | `Authorization: Bearer <fxa_live_api_key>` |
| **Auth (agents)** | `Authorization: Bearer <agent_vc_token>` |
| **Wire format** | OpenAI `chat.completions` |
| **Pricing per model** | https://monetize.fluxapay.xyz/api/llm/models?vendor=baidu-ai-cloud |
| **Top up** | https://proxy-monetize.fluxapay.xyz/llm/topup/initiate |

The same endpoint accepts **two complementary credentials**: a static API key
for human developers, or a short-lived Agent VC for autonomous agents. The
rest of the flow (call, topup, errors) is identical — only the `Bearer`
token differs. Pick the section that fits you and substitute `$AUTH` in
the snippets below.

## 1. Get a credential

### For humans — Monetize API Key

Sign in at https://monetize.fluxapay.xyz/keys and create one. The raw key
(prefix `fxa_live_`) is shown **once** — store it as `MONETIZE_API_KEY`.

```bash
export AUTH=$MONETIZE_API_KEY
```

### For agents — Agent VC (FluxA AgentID)

Agents authenticate with a short-lived (≤ 5 min) **Agent VC** issued by
[FluxA AgentID](https://agentid.fluxapay.xyz) and bound to the wallet
owner's Fluxa account. No static secret needed.

```bash
# (a) Refresh your AgentID JWT if expired
AGENT_JWT=$(curl -sS https://agentid.fluxapay.xyz/refresh \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"<your_agent_id>","token":"<long_lived_token>"}' \
  | jq -r .jwt)

# (b) Mint a fresh Agent VC (one per session, or per call)
AGENT_VC=$(curl -sS https://agentid.fluxapay.xyz/agent/vc/issue \
  -H "Authorization: Bearer $AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{"challenge":"wallet-user-info-lookup","ttl_seconds":300,"audience":"fluxa-wallet-service"}' \
  | jq -r .vc)

export AUTH=$AGENT_VC
```

The VC's `sub` claim (`agent_id`) is logged on every billable call for
per-agent attribution. The wallet owner's balance is debited — same pool
the human's API key would charge.

## 2. List available models

```bash
curl https://monetize.fluxapay.xyz/api/llm/models?vendor=baidu-ai-cloud
```

## 3. Call the model

Same call shape for both credential types — only `$AUTH` differs.

```bash
curl https://proxy-monetize.fluxapay.xyz/llm/baidu-ai-cloud/v1/chat/completions -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" -d '{"model":"<model_id>","messages":[{"role":"user","content":"Hello"}]}'
```

Or with the OpenAI Node SDK:

```ts
import OpenAI from "openai"
const client = new OpenAI({
  baseURL: "https://proxy-monetize.fluxapay.xyz/llm/baidu-ai-cloud/v1",
  apiKey: process.env.AUTH, // fxa_live_… (human) or agent VC (agent)
})
const res = await client.chat.completions.create({
  model: "<model_id>",
  messages: [{ role: "user", content: "Hello" }],
})
```

Response headers report per-call cost:

| Header | Meaning |
|---|---|
| `X-LLM-Cost-Credits` | Integer Units charged for this call |
| `X-LLM-Balance` | Your Baidu AI Cloud balance after the call (signed) |

## 4. First time? Top up Units first

Calls drain your **per-merchant Units balance**. `balance > 0` → calls pass;
`balance < 0` and at the settle threshold → next call returns **402** with an
x402 `accepts` payload. `/llm/topup/initiate` accepts the **same Bearer**
as the call endpoint — either API key or Agent VC.

### Buy a bundle (3-step flow)

```bash
# a. Initiate the topup (returns the x402 accepts payload + resource URL)
curl -X POST https://proxy-monetize.fluxapay.xyz/llm/topup/initiate \
  -H "Authorization: Bearer $AUTH" \
  -H "Content-Type: application/json" \
  -d '{"vendorSlug":"baidu-ai-cloud","packageSlug":"starter"}'

# b. Sign the accepts payload with your Fluxa wallet (x402 v3)
#    Create a mandate sized to costCredits (in Monetize Credits, $1 = 1 Monetize Credit),
#    sign the {x402Version, accepts} body, get xPaymentB64.

# c. Finalize — POST the resource URL with the X-Payment header
curl -X POST "<resource_from_step_a>" \
  -H "Authorization: Bearer $AUTH" \
  -H "X-Payment: <xPaymentB64>"
```

> For agents: mint a fresh `AGENT_VC` before step (a) and again before step
> (c) if more than 5 minutes pass between them — VCs expire.

Full agent prompt with wallet CLI commands:
https://monetize.fluxapay.xyz/marketplace/models/baidu-ai-cloud

## Errors

| Status | Code | Meaning |
|---|---|---|
| **401** | — | Missing or unrecognized credential (not `fxa_live_…` and not a JWT) |
| **401** | `agent_vc_auth_failed` | Agent VC rejected by FluxA Wallet API |
| **403** | `agent_not_authorized` | Agent VC valid but the agent isn't authorized for the wallet |
| **402** | — | Balance below settle threshold — top up and retry |
| **400** | — | Unknown model id, or malformed body |
| **502** | — | Upstream provider unreachable; no metering happens |