mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
296 lines
5.9 KiB
Plaintext
296 lines
5.9 KiB
Plaintext
---
|
|
title: Hanzo Cloud
|
|
description: Core platform infrastructure powering all Hanzo services with API management, data storage, analytics, and billing.
|
|
---
|
|
|
|
# Hanzo Cloud
|
|
|
|
Hanzo Cloud is the core platform infrastructure powering all Hanzo services. It provides API management, data storage, analytics, and billing across the Hanzo ecosystem.
|
|
|
|
## Features
|
|
|
|
- **API Gateway**: Unified API management and routing
|
|
- **Data Storage**: PostgreSQL, Redis, object storage
|
|
- **Analytics**: Real-time usage analytics and metrics
|
|
- **Billing**: Subscription and usage-based billing
|
|
- **Multi-Tenant**: Organization and project isolation
|
|
- **SDK Support**: TypeScript, Python, Go SDKs
|
|
|
|
## Architecture
|
|
|
|
```
|
|
+---------------------------------------------------------------+
|
|
| HANZO CLOUD |
|
|
+---------------------------------------------------------------+
|
|
| |
|
|
| +-----------------------+ +-------------------------------+ |
|
|
| | API Gateway | | Data Layer | |
|
|
| | +------+ +-------+ | | +--------+ +-------------+ | |
|
|
| | | REST | | gRPC | | | | Postgres| | Redis | | |
|
|
| | +------+ +-------+ | | +--------+ +-------------+ | |
|
|
| +-----------------------+ +-------------------------------+ |
|
|
| |
|
|
| +-----------------------+ +-------------------------------+ |
|
|
| | Analytics | | Billing | |
|
|
| | +------+ +-------+ | | +--------+ +-------------+ | |
|
|
| | |Events| |Metrics| | | | Stripe | | Usage Meter | | |
|
|
| | +------+ +-------+ | | +--------+ +-------------+ | |
|
|
| +-----------------------+ +-------------------------------+ |
|
|
| |
|
|
+---------------------------------------------------------------+
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
| Environment | URL |
|
|
|-------------|-----|
|
|
| Production | `https://api.hanzo.ai` |
|
|
| Console | `https://console.hanzo.ai` |
|
|
| Staging | `https://stg.api.hanzo.ai` |
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install SDK
|
|
|
|
```bash
|
|
# TypeScript/JavaScript
|
|
npm install @hanzo/sdk
|
|
|
|
# Python
|
|
pip install hanzo-sdk
|
|
|
|
# Go
|
|
go get github.com/hanzoai/go-sdk
|
|
```
|
|
|
|
### 2. Initialize Client
|
|
|
|
```typescript
|
|
import { Hanzo } from '@hanzo/sdk'
|
|
|
|
const hanzo = new Hanzo({
|
|
apiKey: process.env.HANZO_API_KEY
|
|
})
|
|
```
|
|
|
|
### 3. Make API Calls
|
|
|
|
```typescript
|
|
// List projects
|
|
const projects = await hanzo.projects.list()
|
|
|
|
// Get usage
|
|
const usage = await hanzo.usage.get({
|
|
projectId: 'proj-123',
|
|
startDate: '2024-01-01',
|
|
endDate: '2024-01-31'
|
|
})
|
|
```
|
|
|
|
## Organizations
|
|
|
|
### Create Organization
|
|
|
|
```typescript
|
|
const org = await hanzo.organizations.create({
|
|
name: 'Acme Inc',
|
|
slug: 'acme',
|
|
plan: 'team'
|
|
})
|
|
```
|
|
|
|
### Manage Members
|
|
|
|
```typescript
|
|
// Invite member
|
|
await hanzo.organizations.invite(org.id, {
|
|
email: '[email protected]',
|
|
role: 'admin'
|
|
})
|
|
|
|
// List members
|
|
const members = await hanzo.organizations.members(org.id)
|
|
```
|
|
|
|
## Projects
|
|
|
|
### Create Project
|
|
|
|
```typescript
|
|
const project = await hanzo.projects.create({
|
|
organizationId: org.id,
|
|
name: 'My AI App',
|
|
description: 'AI-powered application'
|
|
})
|
|
```
|
|
|
|
### Project Settings
|
|
|
|
```typescript
|
|
// Configure project
|
|
await hanzo.projects.update(project.id, {
|
|
settings: {
|
|
defaultModel: 'gpt-4o',
|
|
rateLimit: 1000,
|
|
budgetLimit: 100.00
|
|
}
|
|
})
|
|
```
|
|
|
|
## API Keys
|
|
|
|
### Create API Key
|
|
|
|
```typescript
|
|
const key = await hanzo.apiKeys.create({
|
|
projectId: project.id,
|
|
name: 'Production Key',
|
|
scopes: ['inference:read', 'inference:write']
|
|
})
|
|
|
|
console.log(key.key) // Only shown once!
|
|
```
|
|
|
|
### Rotate Key
|
|
|
|
```typescript
|
|
await hanzo.apiKeys.rotate(key.id)
|
|
```
|
|
|
|
## Usage & Billing
|
|
|
|
### Get Usage
|
|
|
|
```typescript
|
|
const usage = await hanzo.usage.get({
|
|
projectId: project.id,
|
|
metric: 'tokens',
|
|
granularity: 'day'
|
|
})
|
|
```
|
|
|
|
### Billing Portal
|
|
|
|
```typescript
|
|
// Get billing portal URL
|
|
const { url } = await hanzo.billing.portal(org.id)
|
|
// Redirect user to Stripe portal
|
|
```
|
|
|
|
### Upgrade Plan
|
|
|
|
```typescript
|
|
await hanzo.billing.upgrade(org.id, {
|
|
plan: 'enterprise',
|
|
seats: 50
|
|
})
|
|
```
|
|
|
|
## Webhooks
|
|
|
|
### Configure Webhook
|
|
|
|
```typescript
|
|
await hanzo.webhooks.create({
|
|
projectId: project.id,
|
|
url: 'https://example.com/webhook',
|
|
events: ['usage.limit_reached', 'key.rotated']
|
|
})
|
|
```
|
|
|
|
### Webhook Events
|
|
|
|
| Event | Description |
|
|
|-------|-------------|
|
|
| `usage.limit_reached` | Usage limit exceeded |
|
|
| `key.created` | New API key created |
|
|
| `key.rotated` | API key rotated |
|
|
| `member.invited` | Team member invited |
|
|
| `invoice.paid` | Invoice payment received |
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# API
|
|
HANZO_API_URL=https://api.hanzo.ai
|
|
HANZO_API_KEY=hzo_xxx
|
|
|
|
# Database
|
|
DATABASE_URL=postgres://user:pass@host:5432/hanzo
|
|
REDIS_URL=redis://localhost:6379
|
|
|
|
# Billing
|
|
STRIPE_SECRET_KEY=sk_xxx
|
|
STRIPE_WEBHOOK_SECRET=whsec_xxx
|
|
|
|
# Storage
|
|
S3_BUCKET=hanzo-uploads
|
|
S3_REGION=us-east-1
|
|
```
|
|
|
|
## Docker Deployment
|
|
|
|
```yaml
|
|
# compose.yml
|
|
services:
|
|
api:
|
|
image: hanzoai/cloud:latest
|
|
ports:
|
|
- "8000:8000"
|
|
environment:
|
|
- DATABASE_URL=postgres://postgres:postgres@db:5432/hanzo
|
|
- REDIS_URL=redis://redis:6379
|
|
depends_on:
|
|
- db
|
|
- redis
|
|
|
|
db:
|
|
image: postgres:16
|
|
volumes:
|
|
- pgdata:/var/lib/postgresql/data
|
|
|
|
redis:
|
|
image: redis:7-alpine
|
|
|
|
volumes:
|
|
pgdata:
|
|
```
|
|
|
|
## SDK Reference
|
|
|
|
### TypeScript
|
|
|
|
```typescript
|
|
import { Hanzo, HanzoError } from '@hanzo/sdk'
|
|
|
|
try {
|
|
const hanzo = new Hanzo({ apiKey: 'xxx' })
|
|
const result = await hanzo.projects.list()
|
|
} catch (error) {
|
|
if (error instanceof HanzoError) {
|
|
console.error(error.code, error.message)
|
|
}
|
|
}
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
from hanzo import Hanzo, HanzoError
|
|
|
|
try:
|
|
hanzo = Hanzo(api_key="xxx")
|
|
projects = hanzo.projects.list()
|
|
except HanzoError as e:
|
|
print(e.code, e.message)
|
|
```
|
|
|
|
### Go
|
|
|
|
```go
|
|
import "github.com/hanzoai/go-sdk"
|
|
|
|
client := hanzo.NewClient("xxx")
|
|
projects, err := client.Projects.List(ctx)
|
|
```
|