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

# 快速入门

> 通过 YCloud 进行身份验证并发送您的第一个 API 请求。

在本快速入门中，您将调用 Balance API 以确认基础 URL 和 API 密钥配置正确。

## 准备工作

您需要准备：

* 一个 YCloud 账户
* 一个 YCloud API 密钥
* `curl` 或其他 HTTP 客户端

## 工作原理

每个服务端 API 请求都使用 `https://api.ycloud.com/v2` 基础 URL，并在 `X-API-Key` 请求头中发送您的密钥。本示例获取账户余额，因为它不会创建或发送任何内容。

## 请求

<Steps>
  <Step title="存储您的 API 密钥">
    在当前终端会话中导出密钥。请将占位符替换为您的真实密钥。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export YCLOUD_API_KEY="YOUR_API_KEY"
    ```

    切勿将 API 密钥提交到源代码管理中。有关生产环境建议，请参阅[身份验证](/zh/api-reference/guides/api-fundamentals/authentication)。
  </Step>

  <Step title="查询余额">
    获取您的账户余额。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl https://api.ycloud.com/v2/balance \
      --header "X-API-Key: $YCLOUD_API_KEY" \
      --header "Accept: application/json"
    ```
  </Step>
</Steps>

## 响应

成功的请求将返回 HTTP `200` 及您的当前余额。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 10.5,
  "currency": "USD"
}
```

| 字段 | 描述 |
| - | - |
| `amount` | 可用账户余额。 |
| `currency` | 账户使用的 ISO 货币代码。 |

如果 API 返回 `401` 或 `403`，请检查请求头名称和 API 密钥。在添加重试机制前，请参阅[处理错误](/zh/api-reference/guides/api-fundamentals/handle-errors)。

<Tip>成功的余额响应表明您的基础 URL 和 API 密钥配合正常。</Tip>

## 后续步骤

<CardGroup cols={2}>
  <Card title="发送 WhatsApp 消息" icon="whatsapp" href="/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message">
    发送模板、文本和媒体消息。
  </Card>

  <Card title="配置 Webhook" icon="webhook" href="/zh/api-reference/guides/api-fundamentals/configure-webhooks">
    接收送达状态更新和入站消息。
  </Card>

  <Card title="处理 API 错误" icon="triangle-exclamation" href="/zh/api-reference/guides/api-fundamentals/handle-errors">
    读取错误响应并设计安全的重试机制。
  </Card>

  <Card title="Balance API 参考" icon="code" href="/api-reference/balance/retrieve-balance">
    查看完整的响应模式并测试该端点。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.