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

# 从模型库下载 Aria 模型包

> 学习如何通过 curl 与 Python 列出、认证并下载量化后的 Aria 模型包。涵盖 JSON 元数据与预签名 URL 流程。

咏唱引擎在公开模型库中托管设备原生模型包。你可以免认证浏览可用模型，但下载模型包需要 API 密钥或会话令牌。本指南将带你完成列出模型、选择量化等级并获取下载链接的全过程。

## 开始之前

* 拥有一个咏唱引擎账户（任意区域）。
* 在控制台创建 API 密钥，或登录以获取会话 JWT。
* 所有示例的基础 URL 为 `https://ariacompute.cn/api`（中国站）。如果你使用国际站，请将主机替换为 `ariacompute.com`。

<Steps>
  <Step title="列出可用模型">
    调用公开模型接口，查看全部模型包及其支持的量化等级。

    ```bash theme={null}
    curl -s https://ariacompute.cn/api/models | jq .
    ```

    响应包含每个模型 slug、可用 quant 值（`int4`、`int8`、`int326`）以及 SDK 兼容性。挑选你需要的 slug 与量化等级。
  </Step>

  <Step title="创建或定位 API 密钥">
    打开[控制台 API 密钥页面](https://ariacompute.cn/dashboard/api-keys)，然后点击 **创建**。复制以 `bfvk-` 开头的完整密钥，它仅展示一次。

    <Tip>
      API 密钥按站点隔离：在 `ariacompute.com` 创建的密钥无法在 `ariacompute.cn` 使用。
    </Tip>
  </Step>

  <Step title="请求下载链接">
    默认情况下，下载接口返回 `302 Found` 重定向至一个短时效的 S3 预签名 URL。使用 `-L` 跟随重定向：

    <CodeGroup>
      ```bash 跟随重定向 theme={null}
      curl -L -H "Authorization: Bearer bfvk-XXXXXXXXXXXXXXXX" \
        "https://ariacompute.cn/api/models/gemma-4-e2b-it/download?quant=int4&sdk=v1.0"
      ```

      ```python Python theme={null}
      import requests

      url = "https://ariacompute.cn/api/models/gemma-4-e2b-it/download"
      headers = {"Authorization": "Bearer bfvk-XXXXXXXXXXXXXXXX"}
      params = {"quant": "int4", "sdk": "v1.0"}

      resp = requests.get(url, headers=headers, params=params, allow_redirects=True)
      print(resp.status_code, len(resp.content))
      ```
    </CodeGroup>

    <Warning>
      预签名 URL 很快过期。不要缓存或分发它们：每次下载都请求一个新的链接。
    </Warning>
  </Step>

  <Step title="改为请求 JSON 元数据">
    如果你想要 URL 但不立即跟随它，发送 `Accept: application/json` 或附加 `?format=json`。

    <CodeGroup>
      ```bash 带 JSON 的 curl theme={null}
      curl -s -H "Authorization: Bearer bfvk-XXXXXXXXXXXXXXXX" \
        -H "Accept: application/json" \
        "https://ariacompute.cn/api/models/gemma-4-e2b-it/download?quant=int4&sdk=v1.0" \
        | jq .
      ```

      ```json 响应 theme={null}
      {
        "mode": "redirect",
        "url": "https://s3.amazonaws.com/aria-bundles/...?X-Amz-Expires=300",
        "filename": "gemma-4-e2b-it_q4.zip"
      }
      ```
    </CodeGroup>

    使用 `url` 字段自行发起下载。`filename` 字段为建议的输出文件名。
  </Step>

  <Step title="目录下载（ZIP 流）">
    当模型包以目录形式存储时，接口会以 `Content-Disposition: attachment` 流式返回 ZIP 文件。直接保存：

    ```bash theme={null}
    curl -L -H "Authorization: Bearer bfvk-XXXXXXXXXXXXXXXX" \
      "https://ariacompute.cn/api/models/gemma-4-e2b-it/download?quant=int4&sdk=v1.0" \
      -o gemma-4-e2b-it_q4.zip
    ```
  </Step>
</Steps>

## 你将获得什么

每个模型包至少包含：

* `weight.bin` —— 量化后的权重
* `config.json` —— 模型配置
* 可选的 tokenizer 附属文件

## 可能遇到的错误

| 状态  | 含义                 |
| --- | ------------------ |
| 401 | 缺失或无效的令牌 / API 密钥。 |
| 404 | 未找到模型 slug 或量化等级。  |
| 429 | 超出限流。等待后重试。        |

## 下一步

* [管理 API 密钥](/guides/manage-api-keys) —— 轮换或吊销密钥。
* [下载引擎与路由最新版](/api-reference/downloads/engine-latest) —— 免认证的发布资源。