# Base URL及鉴权

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

火山方舟API分为模型调用的API（数据面 API），及管理推理接入点等管控相关的管控面 API。它们支持的鉴权方式有所不同，下面介绍方舟API的鉴权方式。

<span id="28e0db57"></span>
# 概念解释

* **数据面 API**：是直接面向**业务数据传输、实时交互、用户请求处理**的接口，聚焦于 “实际业务数据的流转与处理”，是系统对外提供核心服务能力的载体。请求大模型服务的 Chat API、Responses API 均为数据面 API。
* **管控面 API**：用于**系统资源管理、配置控制和状态监控**的接口。它专注于管理和调度数据面及系统资源，是保障系统稳定运行的“控制中枢”。例如，在方舟中用于管理 API Key、基础模型等接口，均属于管控面 API。
* **Base URL**：是构建完整 API 请求 URL 的 “基础模板”，包含**协议（如 http/https）、host（主机域名或 IP）、端口（可选）和基础路径（可选）**，是所有具体接口路径的 “公共前缀”。你可以根据Base URL 加接口/版本等参数拼接出完整接口 URL ，典型结构：`[协议]://[host]/[基础路径（可选）]`

<span id="b77a3928"></span>
# Base URL

> **注意**
>
> 下面给到的数据面 API 与 Coding Plan 支持的 Base URL 不同。Coding Plan 用户请使用正确的 Base URL，避免因地址错误产生额外费用，具体参见 [Base URL](/docs/coding-plan-personal-get-started#7fd1eee7)。

各接口类型对应的 Base URL。
* 数据面 API：https://ark.cn-beijing.volces.com/api/v3
* 管控面 API：https://ark.cn-beijing.volcengineapi.com/
<span id="0fed4817"></span>
# 数据面 API 鉴权

支持两种鉴权方式，API Key 鉴权（简单方便），与 Access Key 鉴权（传统云上资源权限管控，可以分资源组云产品等维度管理，面向企业精细化管理）。
<span id="60db1ed6"></span>
## API Key 签名鉴权

<span id="6011c5a5"></span>
### 前提条件

> **说明**
>
> 方舟平台的新用户？获取 API Key 及 开通模型等准备工作，请参见 [快速入门](/docs/quick-start)。

<span id="d44d13a6"></span>
### 签名构造

在 HTTP 请求 header 中按如下方式添加 `Authorization` header:

```Bash
Authorization: Bearer $ARK_API_KEY
```

示例如下

```Bash
curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seed-2-1-pro-260915",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'
```

* 可按需替换 Model ID。查询 Model ID见 [模型列表](/docs/model-list)。
<span id="21bff83b"></span>
## Access Key 签名鉴权

<span id="3ad1c414"></span>
### 前提条件

你已获取到Access Key。如需创建/查看Access Key，请参见 [API访问密钥管理](https://docs.volcengine.com/docs/6257/64983?lang=zh)。

> 由于主账号的Access Key拥有较大权限，建议你创建IAM用户并授予方舟等权限，然后使用IAM用户的 Access Key 来进行操作，具体请参见[使用 IAM 管理权限](/docs/use-iam-to-manage-permissions)。

<span id="d03b2bb1"></span>
### 使用示例

见 [使用Access Key鉴权](/docs/sdk-common-examples#fa44b913)。

> 通过Access Key 鉴权，model 字段 需配置为 Endpoint ID。

<span id="bdd329d5"></span>
# 管控面 API 鉴权

管控面的API，如管理API Key、管理推理接入点等接口。

<span id="50f355e8"></span>
## Access Key 签名鉴权

获取Access Key。如需创建/查看Access Key，请参见 [API访问密钥管理](https://docs.volcengine.com/docs/6257/64983?lang=zh)。
<span id="c04e9b57"></span>
### 方法：使用示例/说明（简单，推荐）

参见 [SDK 接入指南](https://api.volcengine.com/api-sdk/view?serviceCode=ark&version=2024-01-01&language=Java)。
<span id="101d062c"></span>
### 方法：自行实现签名（实现成本高，不推荐）

1. 使用 Access Key 构造签名。具体方法请参见 [签名方法](https://docs.volcengine.com/docs/6369/67269?lang=zh)。

> 签名用到的方舟相关字段信息：
> * Service：`ark`
> * Region：`cn-beijing`

2. 使用cURL发起请求，请求示例如下：

    ```Bash
    curl -X POST \
      'https://ark.cn-beijing.volcengineapi.com/?Action=ListEndpoints&Version=2024-01-01' \
      -H 'Authorization: HMAC-SHA256 Credential=AKL**/20240710/cn-beijing/ark/request, SignedHeaders=host;x-content-sha256;x-date, Signature=a7a****' \
      -H 'Content-Type: application/json' \
      -H 'Host: ark.cn-beijing.volcengineapi.com' \
      -H 'X-Content-Sha256: 44***' \
      -H 'X-Date: 20240710T042925Z' \
      -d '{}'
    ```