# LayerCloud AI - API Documentation

> LayerCloud AI is an AI gateway: one API key for GPT, Claude, Gemini, DeepSeek and 100+ models, an OpenAI-compatible endpoint that works with Claude Code, Cursor, opencode and any SDK - at about 25% of official prices.

## Base URL

| | |
| --- | --- |
| OpenAI-compatible endpoint | https://ai.layercloud.ir/v1 |
| Documentation | https://ai.layercloud.ir/docs |

## Authentication

All requests authenticate with an API key issued from the console (Tokens page).
Pass it as a Bearer token. **Never put a real key into code you share** - snippets below use the placeholder + LAYERCLOUD_API_KEY environment variable.

```bash
export LAYERCLOUD_API_KEY="lc_..."   # from the Tokens page
```

### First request

```bash
curl https://ai.layercloud.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAYERCLOUD_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "messages": [{"role": "user", "content": "Say hello in one line."}]
  }'
```

## Endpoints

| Endpoint | Purpose |
| --- | --- |
| POST https://ai.layercloud.ir/v1/chat/completions | OpenAI chat completions (streaming via stream: true) |
| POST https://ai.layercloud.ir/v1/responses | OpenAI Responses API |
| GET https://ai.layercloud.ir/v1/models | List the models your key can access |
| POST https://ai.layercloud.ir/v1/embeddings | Embeddings |

The endpoint is drop-in compatible with the OpenAI SDKs: point the base URL
at https://ai.layercloud.ir/v1 and use the same key.

### SDKs

```bash
# OpenAI Python
pip install openai
```

```python
from openai import OpenAI
client = OpenAI(
    base_url="https://ai.layercloud.ir/v1",
    api_key=os.environ["LAYERCLOUD_API_KEY"],
)
client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Hello"}],
)
```

```bash
# OpenAI JavaScript / TypeScript
npm install openai
```

```js
import OpenAI from "openai";
const client = new OpenAI({
    baseURL: "https://ai.layercloud.ir/v1",
    apiKey: process.env.LAYERCLOUD_API_KEY,
});
await client.chat.completions.create({
    model: "gpt-5.6",
    messages: [{ role: "user", content: "Hello" }],
});
```

## Claude Code

```bash
export ANTHROPIC_BASE_URL=https://ai.layercloud.ir
export ANTHROPIC_AUTH_TOKEN=$LAYERCLOUD_API_KEY
claude
```

```bash
# macOS / Linux
export ANTHROPIC_BASE_URL=https://ai.layercloud.ir
export ANTHROPIC_AUTH_TOKEN=$LAYERCLOUD_API_KEY

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://ai.layercloud.ir"
$env:ANTHROPIC_AUTH_TOKEN = $env:LAYERCLOUD_API_KEY
```

Model overrides (if your key may use them):

```bash
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5
```

## OpenAI Codex

Set Codex to use a custom base URL:

```bash
export OPENAI_BASE_URL=https://ai.layercloud.ir/v1
export OPENAI_API_KEY=$LAYERCLOUD_API_KEY
codex
```

## opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "layercloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LayerCloud",
      "options": { "baseURL": "https://ai.layercloud.ir/v1" },
      "apiKey": "{env:LAYERCLOUD_API_KEY}",
      "models": {
        "gpt-5.6": { "name": "GPT-5.6" }
      }
    }
  }
}
```

```bash
opencode run --model layercloud/gpt-5.6 "Hello"
```

## KiloCode

Add the provider in the KiloCode settings (API Providers):
base URL https://ai.layercloud.ir/v1, API key style Bearer with your LayerCloud key.

## Prime Agent (prime CLI)

```bash
export OPENAI_BASE_URL=https://ai.layercloud.ir/v1
export OPENAI_API_KEY=$LAYERCLOUD_API_KEY
prime
```

## Aider

```bash
export OPENAI_API_BASE=https://ai.layercloud.ir/v1
export OPENAI_API_KEY=$LAYERCLOUD_API_KEY
aider --model openai/gpt-5.6
```

## Continue (VS Code / JetBrains)

config.json:

```json
{
  "models": [{
    "title": "LayerCloud GPT-5.6",
    "provider": "openai",
    "model": "gpt-5.6",
    "apiBase": "https://ai.layercloud.ir/v1",
    "apiKey": "$LAYERCLOUD_API_KEY"
  }]
}
```

## Editors

### Cursor / Windsurf / VS Code (OpenAI-compatible)

- Base URL: https://ai.layercloud.ir/v1
- API key: your LayerCloud key
- Model: any model from the catalog (see https://ai.layercloud.ir/#pricing)

### OpenClaude

Point OpenClaude at the Anthropic-compatible base: https://ai.layercloud.ir

## Notes

- Prices are per 1M tokens and are billed from your pay-as-you-go balance (see https://ai.layercloud.ir/#pricing for the live table).
- Streaming (SSE) is supported on chat completions and Responses.
- Keys can be scoped with quotas and model allow-lists from the console Tokens page.
- If a model is missing from /v1/models, your key's allow-list may not include it.