# API 调用场景

OpenAI-compatible、Grok、Images、Videos、Web Search、Embeddings、Usage 与 Node.js SDK 的最小调用模板。适合把 Clomio 接入程序、脚本或服务。

完整参数见 [API 概述](#/api-usage)、[Responses](#/api-responses)、[Images](#/api-images)、[Videos](#/api-videos)、[Web Search](#/api-websearch)。

---

## OpenAI SDK:Responses、Chat、图片、Embeddings

OpenAI-compatible 客户端统一:

```python
from openai import OpenAI
client = OpenAI(api_key="你的 OpenAI/Codex 分组密钥", base_url="https://api.clomio.ai/v1")
```

Responses:

```python
r = client.responses.create(
    model="控制台里的模型名",
    input="把下面这段日志总结为 3 个要点: ...",
)
print(r.output_text)
```

Chat Completions:

```python
r = client.chat.completions.create(
    model="控制台里的模型名",
    messages=[{"role": "user", "content": "写一个 curl 调试清单"}],
)
print(r.choices[0].message.content)
```

图片:

```python
import base64
r = client.images.generate(
    model="控制台里的图片模型名",
    prompt="一张干净的 SaaS 控制台插画",
    size="1024x1024",
)
open("out.png", "wb").write(base64.b64decode(r.data[0].b64_json))
```

Embeddings:

```python
r = client.embeddings.create(
    model="控制台里的 embedding 模型名",
    input=["第一段文档", "第二段文档"],
)
print(len(r.data[0].embedding))
```

排错顺序:先 `GET /v1/models` 看列表,再发最小请求;不要自行拼模型详情查询路径。

---

## Grok CLI:干净环境最小启动

Grok CLI 使用 Grok 分组 Key,Base URL 带 `/v1`。控制台模板可能给 `grok-build` 等示例模型,真实模型以分组开放列表为准。

```bash
export GROK_MODELS_BASE_URL="https://api.clomio.ai/v1"
export XAI_API_KEY="你的 Grok 分组密钥"

# 排除 OPENAI_* / 旧 GROK_* 干扰的一次性启动
env -i PATH="$PATH" \
  GROK_MODELS_BASE_URL="$GROK_MODELS_BASE_URL" \
  XAI_API_KEY="$XAI_API_KEY" \
  grok --model "控制台里的 Grok 对话模型"
```

也可写入 `~/.grok/config.toml`:

```toml
[endpoints]
models_base_url = "https://api.clomio.ai/v1"

[model.grok-build]
model = "控制台里的 Grok 对话模型"
env_key = "XAI_API_KEY"
```

---

## Grok videos only:只做视频

视频能力只在 Grok 分组开放。Base URL 仍是 `https://api.clomio.ai/v1`,提交后按返回的任务 ID 轮询。新接入优先使用 xAI 官方字段 `duration`、`aspect_ratio`、`resolution`;旧客户端的 `seconds`、`size` 只作为兼容字段。

```bash
curl https://api.clomio.ai/v1/videos/generations \
  -H "Authorization: Bearer 你的 Grok 分组密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台里的 Grok 视频模型名",
    "prompt": "雨后城市街道,霓虹倒影,电影质感",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
```

```bash
curl https://api.clomio.ai/v1/videos/video_xxx \
  -H "Authorization: Bearer 你的 Grok 分组密钥"
```

如果返回 404,通常是 Key 不在 Grok 分组、路径写错或分组未开放该模型;如果返回 403 `Video generation is not enabled for this group`,说明 Grok 分组未开视频能力;如果返回 429,创建端看上游 rate-limit/`Retry-After`,轮询端降低到 5~10 秒以上。

---

## 查询 Key 用量、余额和限速

`GET /v1/usage` 可用来确认一个 Key 是否有效、余额/套餐剩余、API Key quota、5h/1d/7d 限速和模型用量:

```bash
curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29' \
  -H "Authorization: Bearer 你的密钥"
```

看返回里的:

- `mode: "quota_limited"`:这个 Key 配了独立额度或限速,重点看 `quota` 和 `rate_limits`。
- `mode: "unrestricted"`:没有 Key 级限制,重点看 `balance`、`subscription`、`remaining`。
- `usage.today.actual_cost` / `usage.total.actual_cost`:实际扣费口径。

---

## Grok 搜索:让模型带联网信息回答

使用 Grok 分组 Key,Base URL 是 `https://api.clomio.ai/v1`。推荐主路径是 Responses tool,因为它能使用官方 `web_search` 参数并直接返回带引用的回答:

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer 你的 Grok 分组密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台里的 Grok 对话模型",
    "input": "检索今天 xAI Grok API 有哪些更新,并给出引用",
    "tools": [{"type":"web_search"}],
    "store": false
  }'
```

高级搜索参数放在 `tools[]` 里,不是 `/v1/web_search` 顶层:

```json
{
  "model": "grok-4.3",
  "input": "只检索 x.ai 域名,概括 Grok API Web Search 能力",
  "tools": [{
    "type": "web_search",
    "filters": { "allowed_domains": ["x.ai"] },
    "enable_image_search": true
  }],
  "store": false
}
```

只想拿 sources-list、不需要模型总结时,再用 Clomio 简化端点:

```bash
curl https://api.clomio.ai/v1/web_search \
  -H "Authorization: Bearer 你的 Grok 分组密钥" \
  -H "Content-Type: application/json" \
  -d '{"query":"今天 xAI Grok API 有哪些更新?","max_results":5}'
```

不要用 Claude/OpenAI 分组 Key 调 Web Search;Web Search 走 Grok。

---

## Grok / OpenAI 图片:生成一张图

图片端点走 OpenAI-compatible Base URL,即 `https://api.clomio.ai/v1`。Images 可用 OpenAI 分组或 Grok 分组,但参数习惯不同。

OpenAI 图片模型通常用 `gpt-image-*` + `size`:

```bash
curl https://api.clomio.ai/v1/images/generations \
  -H "Authorization: Bearer 你的 OpenAI 分组密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台里的 OpenAI 图片模型名",
    "prompt": "一张极简风格的终端 AI 助手图标,深色背景,蓝紫渐变",
    "size": "1024x1024"
  }'
```

Grok Imagine 通常用 `grok-imagine-*` + `aspect_ratio` / `n`,默认返回 URL:

```bash
curl https://api.clomio.ai/v1/images/generations \
  -H "Authorization: Bearer 你的 Grok 分组密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台里的 Grok 图片模型名",
    "prompt": "A futuristic city skyline at night",
    "n": 1,
    "aspect_ratio": "16:9"
  }'
```

如果返回平台不支持或模型不存在,优先检查:Key 是否属于对应分组、模型名是否来自控制台、端点是否是 `/v1/images/*`。如果报 `images endpoint requires an image model`,说明实际请求落到的不是图片模型；请换控制台列出的图片模型，并带 `x-request-id` 提交工单。

---

## Agent 客户端协议速查:Codex / Hermes / OpenClaw

接 Agent/CLI 前先用 curl 验证协议,再写客户端配置。

Codex 非交互执行:

```toml
model_provider = "clomio"
model = "控制台里的 Codex/OpenAI 模型名"

[model_providers.clomio]
name = "clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
```

```bash
export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥"
codex exec "阅读当前仓库,只输出构建和测试命令"
```

Hermes 按协议拆 provider:

```yaml
custom_providers:
  - name: clomio-responses
    base_url: https://api.clomio.ai/v1
    key_env: CLOMIO_API_KEY
    api_mode: codex_responses
    models: [{ id: gpt-5.4, context_window: 128000 }]
  - name: clomio-openai
    base_url: https://api.clomio.ai/v1
    key_env: CLOMIO_API_KEY
    api_mode: chat_completions
    models: [{ id: gpt-5.4, context_window: 128000 }]
  - name: clomio-anthropic
    base_url: https://api.clomio.ai
    key_env: CLOMIO_CLAUDE_KEY
    api_mode: anthropic_messages
    models: [{ id: claude-sonnet-4-6, context_window: 200000 }]
```

OpenClaw 同样拆成 `openai-responses`、`openai-completions`、`anthropic-messages` 三个 provider,默认模型写 `provider/model`,不要把 Claude、Grok、GPT 混到一个 provider。

---

## Node.js OpenAI SDK:最小可运行脚本

适合把 Clomio 接进自己的 Node.js 项目。OpenAI-compatible 一律带 `/v1`:

```bash
npm install openai
export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥"
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLOMIO_API_KEY,
  baseURL: "https://api.clomio.ai/v1",
});

const response = await client.responses.create({
  model: "控制台里的 OpenAI/Codex 模型名",
  input: "用三句话写一份上线前检查清单。",
});

console.log(response.output_text);
```

如果你要换线路,只替换域名并保留 `/v1`,例如 `https://crs.qazwc.com/v1`。不要改成 Claude 的根地址规则。

---