# @elizaos/plugin-elizacloud

Eliza Cloud plugin for elizaOS agents. The TypeScript package is backed by
`@elizaos/cloud-sdk`, so runtime Cloud API calls, auth helpers, route wrappers,
TTS, STT, image generation, containers, and gateway relay code use the same SDK
surface as other Eliza Cloud clients.

## Installation

```bash
npm install @elizaos/plugin-elizacloud
# or
bun add @elizaos/plugin-elizacloud
```

Register the plugin with your agent runtime:

```typescript
import { elizaOSCloudPlugin } from "@elizaos/plugin-elizacloud";

const agent = new Agent({
  plugins: [elizaOSCloudPlugin],
});
```

## SDK Contract

The TypeScript package has a hard dependency on `@elizaos/cloud-sdk`.
Development checkouts resolve it with `workspace:*`; published packages are
expected to consume the npm-published SDK version.

Runtime code must not build direct Eliza Cloud HTTP calls by hand. Use the SDK
helpers in `src/utils/sdk-client.ts`:

| Helper | Use |
| --- | --- |
| `createCloudApiClient(runtime)` | API-base requests such as `/responses`, `/embeddings`, `/models`, auth validation, containers, and relay JSON endpoints |
| `createCloudApiClient(runtime, true)` | Embedding requests that may use `ELIZAOS_CLOUD_EMBEDDING_URL` / `ELIZAOS_CLOUD_EMBEDDING_API_KEY` |
| `createElizaCloudClient(runtime)` | High-level SDK helpers and generated `client.routes.*` wrappers |
| `src/utils/cloud-api.ts` | Backwards-compatible re-export of SDK classes and types |

`ELIZAOS_CLOUD_BASE_URL` remains the API base URL and defaults to
`https://elizacloud.ai/api/v1`. `createElizaCloudClient` derives the site
root from that API URL when generated SDK route wrappers need `/api/v1/...`
paths.

`src/providers/openai.ts` is the one intentional transport adapter that
passes the configured base URL to the Vercel AI SDK's OpenAI-compatible client.
It is not a hand-rolled Cloud API fetch path.

## Runtime Coverage

| Plugin capability | SDK path |
| --- | --- |
| Text generation (`TEXT_NANO`, `TEXT_SMALL`, `TEXT_MEDIUM`, `TEXT_LARGE`, `TEXT_MEGA`, response handler, planner) | `CloudApiClient.requestRaw("POST", "/responses", ...)` |
| Structured object generation | `CloudApiClient.requestRaw("POST", "/responses", ...)` |
| Research generation | `CloudApiClient.requestRaw("POST", "/responses", ...)` |
| Text embeddings | `CloudApiClient.requestRaw("POST", "/embeddings", ...)` |
| Image generation | `ElizaCloudClient.generateImage(...)` |
| Image description | generated SDK route `client.routes.postApiV1ChatCompletionsRaw(...)` |
| Text-to-speech | generated SDK route `client.routes.postApiV1VoiceTts(...)` |
| Audio transcription | generated SDK route `client.routes.postApiV1VoiceSttRaw(...)` |
| Model registry and credit status | `CloudApiClient` |
| Device auth and API-key validation | `CloudApiClient` |
| Cloud containers | `CloudApiClient` supplied by `CloudAuthService` |
| Managed gateway relay | `CloudApiClient` |
| Credits, app credits, and hosted checkout | `ElizaCloudClient.createCreditsCheckout(...)`, `getAppCreditsBalance(...)`, `createAppCreditsCheckout(...)` |
| Agent/app charge requests | `ElizaCloudClient.createAppCharge(...)`, `createAppChargeCheckout(...)` |
| x402 payment requests and settlement | `ElizaCloudClient.createX402PaymentRequest(...)`, `getX402Supported(...)`, `settleX402PaymentRequest(...)` |
| Affiliate links and creator payouts | `createAffiliateCode(...)`, `linkAffiliateCode(...)`, `getAppEarnings(...)`, `withdrawAppEarnings(...)`, `createRedemption(...)` |

The only remaining runtime-adjacent `fetch()` usage is in the plugin test block
for downloading a public audio fixture. It is not an Eliza Cloud API call.

## Payments And Monetization

The plugin exposes one local route family for Cloud money flows:
`/api/cloud/billing/*`. It forwards to the authenticated Cloud API using the
same Cloud key as the rest of the plugin, so app UIs and agents do not need to
handle Cloud credentials directly.

Supported local aliases:

| Local route | Cloud route |
| --- | --- |
| `/api/cloud/billing/credits/*` | `/api/v1/credits/*` |
| `/api/cloud/billing/app-credits/*` | `/api/v1/app-credits/*` |
| `/api/cloud/billing/x402/*` | `/api/v1/x402/*` |
| `/api/cloud/billing/apps/{appId}/charges/*` | `/api/v1/apps/{appId}/charges/*` |
| `/api/cloud/billing/apps/{appId}/earnings/*` | `/api/v1/apps/{appId}/earnings/*` |
| `/api/cloud/billing/apps/{appId}/monetization` | `/api/v1/apps/{appId}/monetization` |
| `/api/cloud/billing/affiliates/*` | `/api/v1/affiliates/*` |
| `/api/cloud/billing/redemptions/*` | `/api/v1/redemptions/*` |

Agent-initiated charges should use app charge requests for Stripe/OxaPay credit
checkout or x402 payment requests for direct crypto settlement. Both request
types accept callback channel metadata, so successful or failed payment events
can be written back into the room where the charge was initiated.

## Configuration

Get an API key from
[https://www.elizacloud.ai/dashboard/api-keys](https://www.elizacloud.ai/dashboard/api-keys).

| Setting | Description | Default |
| --- | --- | --- |
| `ELIZAOS_CLOUD_API_KEY` | API key used for authenticated Cloud requests | Required |
| `ELIZAOS_CLOUD_BASE_URL` | Eliza Cloud API base URL | `https://elizacloud.ai/api/v1` |
| `ELIZAOS_CLOUD_ENABLED` | Enables container provisioning, device auth, bridge, and backup services | `false` |
| `ELIZAOS_CLOUD_NANO_MODEL` | Nano/cheapest model override | `NANO_MODEL` or `gemma-4-31b` |
| `ELIZAOS_CLOUD_SMALL_MODEL` | Small/fast model override | `SMALL_MODEL` or `gemma-4-31b` |
| `ELIZAOS_CLOUD_MEDIUM_MODEL` | Medium planning model override | `MEDIUM_MODEL` or small model |
| `ELIZAOS_CLOUD_LARGE_MODEL` | Large model override | `LARGE_MODEL` or `gemma-4-31b` |
| `ELIZAOS_CLOUD_MEGA_MODEL` | Mega model override | `MEGA_MODEL` or large model |
| `ELIZAOS_CLOUD_RESPONSE_HANDLER_MODEL` | Response handler model override | small model |
| `ELIZAOS_CLOUD_ACTION_PLANNER_MODEL` | Action planner model override | large model |
| `ELIZAOS_CLOUD_RESEARCH_MODEL` | Research model override | large model |
| `ELIZAOS_CLOUD_EMBEDDING_MODEL` | Embedding model | `text-embedding-3-small` |
| `ELIZAOS_CLOUD_EMBEDDING_URL` | Optional custom embedding API base URL | unset |
| `ELIZAOS_CLOUD_EMBEDDING_API_KEY` | Optional custom embedding API key | `ELIZAOS_CLOUD_API_KEY` |
| `ELIZAOS_CLOUD_EMBEDDING_DIMENSIONS` | Embedding vector size | `1536` |
| `ELIZAOS_CLOUD_IMAGE_DESCRIPTION_MODEL` | Vision model used for image descriptions | `gpt-5.4-mini` |
| `ELIZAOS_CLOUD_IMAGE_DESCRIPTION_MAX_TOKENS` | Max image-description response tokens | `8192` |
| `ELIZAOS_CLOUD_IMAGE_GENERATION_MODEL` | Image generation model override | `google/nano-banana-2/text-to-image` |
| `ELIZAOS_CLOUD_TTS_MODEL` | Text-to-speech model | `gpt-5-mini-tts` |
| `ELIZAOS_CLOUD_USE_STT` | Per-service opt-in for Cloud STT when `ELIZAOS_CLOUD_ENABLED` is unset (capability-only mode) | unset |
| `ELIZAOS_CLOUD_STT_TIMEOUT_MS` | Cloud STT request timeout | `60000` |
| `ELIZAOS_CLOUD_EXPERIMENTAL_TELEMETRY` | Enables experimental telemetry metadata | `false` |

Browser builds must not receive secrets directly. Use
`ELIZAOS_CLOUD_BROWSER_BASE_URL` and `ELIZAOS_CLOUD_BROWSER_EMBEDDING_URL` for
browser-only proxy endpoints.

## Usage Examples

```typescript
import { ModelType } from "@elizaos/core";

const text = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Summarize the current agent state.",
});

// Structured output: route through TEXT_* with `responseSchema` (native tool calling).
const structured = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Return a JSON user profile with name and role.",
  responseSchema: {
    type: "object",
    properties: { name: { type: "string" }, role: { type: "string" } },
    required: ["name", "role"],
  },
});

const embedding = await runtime.useModel(ModelType.TEXT_EMBEDDING, {
  text: "Hello, world!",
});

const speech = await runtime.useModel(ModelType.TEXT_TO_SPEECH, {
  text: "Cloud text to speech is active.",
});

// STT: accepts Buffer/Blob/File bytes, an http(s) audio URL string, or
// core TranscriptionParams ({ audioUrl }). URL fetches go through the
// SSRF guard. Requires ELIZAOS_CLOUD_ENABLED=true or ELIZAOS_CLOUD_USE_STT=true.
const transcript = await runtime.useModel(ModelType.TRANSCRIPTION, audioBuffer);
```

## Adding Cloud Calls

1. Prefer an existing high-level SDK method when one exists.
2. Otherwise use a generated `createElizaCloudClient(runtime).routes.*` wrapper.
3. Use `createCloudApiClient(runtime)` for raw API-base endpoints that do not
   yet have a generated wrapper.
4. Keep all Eliza Cloud API auth/header/base-URL behavior inside the SDK helper
   layer.
5. Do not add direct `fetch()` calls for Eliza Cloud API routes in runtime code.

When the Cloud API adds or changes public routes, update the SDK first (see the Development section below), then update this plugin to consume the new SDK route or helper.

## Development

```bash
bun run --cwd plugins/plugin-elizacloud typecheck
bun run --cwd plugins/plugin-elizacloud test
bun run --cwd plugins/plugin-elizacloud build
```

When the Cloud API adds or changes public routes, update `@elizaos/cloud-sdk`
first, then update this plugin to consume the new SDK route or helper:

```bash
bun run --cwd packages/cloud/sdk build
bun run --cwd packages/cloud/sdk typecheck
bun run --cwd packages/cloud/sdk test
```

## Publishing

This plugin is published to npm as `@elizaos/plugin-elizacloud`. Publishing requires a compatible `@elizaos/cloud-sdk` release because the plugin depends on it directly.

## License

MIT