> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> 创建 API 密钥，并从外部程序、SDK 或外部工具调用 Moxus AI。

本页讲的是如何在 Moxus AI 外部使用你创建的 API 密钥发起请求，例如在服务端代码、命令行、SDK 或外部工具中调用模型。

<Info>
  “对话”是网页端测试环境，登录后会自动使用平台内部的虚拟密钥发起测试请求，不需要你手动配置刚创建的 API 密钥。只有从外部程序、SDK 或外部工具调用时，才需要使用“API 密钥”页面创建的 `sk-` 密钥。
</Info>

## 调用流程

<Steps>
  <Step title="注册并登录">
    访问 `https://moxus.cloud`，使用邮箱注册或平台已启用的第三方登录方式进入控制台。
  </Step>

  <Step title="准备余额">
    进入“付款与账单”页面确认账户有可用余额；可以通过在线充值、兑换码或平台赠送额度获得余额。
  </Step>

  <Step title="创建外部调用用的 API 密钥">
    进入“API 密钥”页面创建以 `sk-` 开头的密钥。这个密钥用于外部代码、SDK、脚本或外部工具，不是“对话”必填项。
  </Step>

  <Step title="选择协议和模型">
    在“模型广场”页面复制模型名称，并根据你使用的协议选择对应接口地址和请求写法。
  </Step>

  <Step title="从外部发起请求">
    使用 cURL 或对应协议的 SDK 发起请求。多数项目可以先从 OpenAI SDK 开始。
  </Step>
</Steps>

<Warning>
  API 密钥只在创建时完整展示。请立即复制并妥善保存，不要写入前端代码、公开仓库、截图或聊天记录。
</Warning>

## 选择调用方式

不同协议的接口地址、认证方式和请求体不同。不要把 OpenAI 的请求体直接发到 Anthropic 或 Google 原生接口。

| 调用方式         | 接口地址（Base URL）               | 认证方式                         | 适合场景                                        |
| ------------ | ---------------------------- | ---------------------------- | ------------------------------------------- |
| OpenAI 兼容    | `https://moxus.cloud/v1`     | `Authorization: Bearer 你的密钥` | OpenAI SDK、Chat Completions、Images、绝大多数外部工具 |
| Anthropic 兼容 | `https://moxus.cloud`        | `x-api-key: 你的密钥`            | Claude 原生 Messages 接口或 Anthropic SDK        |
| Google 兼容    | `https://moxus.cloud/v1beta` | 查询参数 `?key=你的密钥` 或客户端对应配置    | Google 原生接口或 Google 兼容客户端                   |

## 不使用 SDK：直接 HTTP 调用

如果你想先确认密钥、模型和接口地址是否可用，可以不安装任何 AI SDK，直接发送 HTTP 请求。请按你的协议选择对应示例：OpenAI、Anthropic、Google 三种兼容接口的地址、认证方式和请求体都不同。每个示例都直接填写密钥，不需要先在终端或其他配置文件中设置环境变量；只需将代码里的 `你的密钥` 替换为你的实际密钥。

<Tabs>
  <Tab title="OpenAI 兼容">
    OpenAI 兼容接口适合大多数聊天、工具和 SDK 迁移场景，请求地址使用 `https://moxus.cloud/v1/chat/completions`，认证方式是 `Authorization: Bearer ...`。

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://moxus.cloud/v1/chat/completions \
        -H "Authorization: Bearer 你的密钥" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "gpt-5.4-mini",
          "messages": [
            {"role": "user", "content": "请用一句话介绍你自己"}
          ]
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic 兼容">
    Anthropic 兼容接口适合 Claude 原生 Messages 写法，请求地址使用 `https://moxus.cloud/v1/messages`，认证方式是 `x-api-key`，并需要传入 `anthropic-version` 请求头。

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://moxus.cloud/v1/messages \
        -H "x-api-key: 你的密钥" \
        -H "anthropic-version: 2023-06-01" \
        -H "content-type: application/json" \
        -d '{
          "model": "claude-opus-4-6",
          "max_tokens": 512,
          "messages": [
            {"role": "user", "content": "请用一句话介绍你自己"}
          ]
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Google 兼容">
    Google 兼容接口适合 Google 原生 `generateContent` 写法，请求地址使用 `https://moxus.cloud/v1beta`，密钥放在 `key` 查询参数中。

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://moxus.cloud/v1beta/models/gemini-2.5-pro:generateContent?key=你的密钥" \
        -H "Content-Type: application/json" \
        -d '{
          "contents": [
            {
              "parts": [
                {"text": "请用一句话介绍你自己"}
              ]
            }
          ]
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## SDK 接入说明

SDK 本质上是帮你组装请求。接入 Moxus AI 时，通常只需要确认三件事：

| 配置项    | 填写方式                                                                                |
| ------ | ----------------------------------------------------------------------------------- |
| API 密钥 | 使用“API 密钥”页面创建的 `sk-` 密钥                                                            |
| 接口地址   | 按协议填写 `https://moxus.cloud/v1`、`https://moxus.cloud` 或 `https://moxus.cloud/v1beta` |
| 模型名称   | 在“模型广场”复制完整模型名称                                                                     |

如果你只是想完成第一次调用，优先使用 OpenAI SDK。只有项目已经依赖 Claude 原生 Messages 或 Google 原生接口时，再使用 Anthropic SDK 或 Google SDK。

<Warning>
  为便于首次调用，下面的示例将密钥直接写在 `API_KEY` 变量中。复制后只需替换 `你的密钥` 即可运行；不要将填入实际密钥的文件提交到公开仓库或发送给他人。正式项目仍建议改用环境变量或服务端密钥管理。
</Warning>

安装依赖时，选择 `npm` 或 `pnpm` 其中一种即可，两者是替代关系。

## OpenAI SDK

如果你不确定该选哪种方式，优先使用 OpenAI 兼容接口。它适合大多数模型调用、SDK 和外部工具。

安装依赖：

<CodeGroup>
  ```bash npm theme={null}
  npm install openai tsx
  ```

  ```bash pnpm theme={null}
  pnpm add openai tsx
  ```
</CodeGroup>

复制下面代码时，Python 示例保存为 `openai_example.py`，TypeScript 示例保存为 `openai-example.ts`。

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  API_KEY = "你的密钥"

  client = OpenAI(
      api_key=API_KEY,
      base_url="https://moxus.cloud/v1",
  )

  resp = client.chat.completions.create(
      model="gpt-5.4-mini",
      messages=[
          {"role": "user", "content": "请用一句话介绍你自己"},
      ],
  )

  print(resp.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const API_KEY = "你的密钥";

  const client = new OpenAI({
    apiKey: API_KEY,
    baseURL: "https://moxus.cloud/v1",
  });

  const response = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [{ role: "user", content: "请用一句话介绍你自己" }],
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

## Anthropic SDK

如果你的项目使用 Claude 原生 Messages 写法，请使用 Anthropic SDK。这里的 Base URL 填 `https://moxus.cloud`，SDK 会自行拼接 `/v1/messages`。

安装依赖：

<CodeGroup>
  ```bash npm theme={null}
  npm install @anthropic-ai/sdk tsx
  ```

  ```bash pnpm theme={null}
  pnpm add @anthropic-ai/sdk tsx
  ```
</CodeGroup>

复制下面代码时，Python 示例保存为 `anthropic_example.py`，TypeScript 示例保存为 `anthropic-example.ts`。

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from anthropic import Anthropic

  API_KEY = "你的密钥"

  client = Anthropic(
      api_key=API_KEY,
      base_url="https://moxus.cloud",
      http_client=httpx.Client(
          trust_env=False,
          timeout=60.0,
      ),
  )

  message = client.messages.create(
      model="claude-opus-4-6",
      max_tokens=512,
      messages=[
          {"role": "user", "content": "请用一句话介绍你自己"},
      ],
  )

  print(message.content[0].text)
  ```

  ```typescript TypeScript theme={null}
  import Anthropic from "@anthropic-ai/sdk";

  const API_KEY = "你的密钥";

  const client = new Anthropic({
    apiKey: API_KEY,
    baseURL: "https://moxus.cloud",
  });

  const message = await client.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 512,
    messages: [{ role: "user", content: "请用一句话介绍你自己" }],
  });

  const text = message.content.find((block) => block.type === "text")?.text;
  console.log(text);
  ```
</CodeGroup>

## Google SDK

如果你的项目使用 Google 原生接口，请使用 Google GenAI SDK。Google SDK 的 `base_url` / `baseUrl` 填 `https://moxus.cloud`，并把 API 版本设为 `v1beta`，不要在这里重复写 `/v1beta`。

安装依赖：

<CodeGroup>
  ```bash npm theme={null}
  npm install @google/genai tsx
  ```

  ```bash pnpm theme={null}
  pnpm add @google/genai tsx
  ```
</CodeGroup>

复制下面代码时，Python 示例保存为 `google_example.py`，TypeScript 示例保存为 `google-example.ts`。

<CodeGroup>
  ```python Python theme={null}
  from google import genai
  from google.genai import types

  API_KEY = "你的密钥"

  client = genai.Client(
      api_key=API_KEY,
      http_options=types.HttpOptions(
          api_version="v1beta",
          base_url="https://moxus.cloud",
      ),
  )

  response = client.models.generate_content(
      model="gemini-2.5-pro",
      contents="请用一句话介绍你自己",
  )

  print(response.text)
  ```

  ```typescript TypeScript theme={null}
  import { GoogleGenAI } from "@google/genai";

  const API_KEY = "你的密钥";

  const ai = new GoogleGenAI({
    apiKey: API_KEY,
    httpOptions: {
      apiVersion: "v1beta",
      baseUrl: "https://moxus.cloud",
    },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "请用一句话介绍你自己",
  });

  console.log(response.text);
  ```
</CodeGroup>

## 验证调用结果

外部请求成功后，进入“控制台与用量”页面查看 API 活动记录。记录中会展示调用时间、API 密钥、模型名称、输入 Token、输出 Token、总 Token 和消耗。

如果你只是在网页“对话”里测试，日志同样会出现，但它使用的是平台内部虚拟密钥，不代表你创建的外部 API 密钥已经配置成功。要验证外部 API 密钥，请运行本页中的 cURL 或 SDK 示例。

## 常见错误

| 现象                   | 常见原因                     | 处理方式                                 |
| -------------------- | ------------------------ | ------------------------------------ |
| `401 Unauthorized`   | 密钥错误、请求头不匹配或密钥已禁用        | 检查是否使用了当前协议对应的认证方式                   |
| `insufficient quota` | 账户余额或密钥额度不足              | 前往“付款与账单”充值，或调整密钥额度                  |
| `model not found`    | 模型名称填写错误、模型未开放或密钥限制了模型范围 | 在“模型广场”复制完整模型名称                      |
| 请求体报错                | 把某协议的请求体发到了另一个协议接口       | 按 OpenAI、Anthropic、Google 分别使用对应代码示例 |
| 连接超时                 | 接口地址（Base URL）填写错误或网络不可达 | 检查协议对应的接口地址                          |

## 下一步

* 管理密钥限制：参阅 [API 密钥](/zh/platform/account-and-keys)。
* 查看模型价格：参阅 [模型广场与定价](/zh/overview/models-and-pricing)。
* 配置客户端：参阅 [Cursor 接入](/zh/integrations/clients/cursor)。