# IAM API Key 最佳实践

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

火山方舟部分模型服务已可使用 IAM API Key 鉴权。本文说明方舟 API Key 与 IAM API Key 的差异，并演示如何用 IAM API Key 完成鉴权、跨产品调用、用量查询与费用分账。

## 什么是 IAM API Key

**IAM API Key** 是在火山引擎访问控制（Identity and Access Management，简称 IAM）控制台创建、归属于某个 IAM 用户的 API 鉴权凭证。

IAM API Key 具备以下能力：

- **统一多云鉴权**：一把 API Key 可通过 IAM 权限策略调用多个已支持 API Key 鉴权的火山云产品，包含火山方舟。
- **集中生命周期管理**：创建、轮换、禁用、删除均在 IAM 控制台统一操作，与 IAM 用户绑定。
- **细粒度权限控制**：通过 IAM 预设或自定义权限策略约束可访问的产品、资源与操作。
- **可审计**：API Key 的使用与权限变更纳入 IAM 审计日志。

IAM API Key 与方舟控制台创建的 API Key 是**并列的两种入口**，均可用于调用火山方舟。IAM 相关的基本概念（IAM 用户、用户组、权限策略等）详情请参见 [使用 IAM 管理权限](/docs/use-iam-to-manage-permissions)。

## 方舟 API Key 与 IAM API Key 对比

两种 API Key 均可调用火山方舟，且均可通过 IAM 权限策略扩展至其他火山云产品。两者主要差异在于**创建入口**与**生命周期管理**，请按需选择。

| 对比项 | 方舟控制台创建的 API Key | IAM 控制台创建的 API Key |
| --- | --- | --- |
| 创建入口 | 方舟控制台 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面 | [IAM 控制台](https://console.volcengine.com/iam) |
| 管理入口 | 方舟控制台 + IAM 控制台 | 仅 IAM 控制台<blockquote>IAM 控制台创建的 API Key 不在方舟 **API Key 管理** 页面展示。</blockquote> |
| 默认权限 | 自动绑定方舟预设权限策略，具备方舟访问权限 | 需手动为所属 IAM 用户绑定方舟权限策略 |
| 扩展其他云产品权限 | 通过 IAM 用户管理为 API Key 添加其他产品权限策略 | 通过 IAM 用户绑定其他产品权限策略 |
| 支持的方舟订阅 | 支持全部方舟订阅<blockquote>按量付费、Coding Plan 使用普通方舟 API Key，其中 Coding Plan 需切换到专属 Base URL `https://ark.cn-beijing.volces.com/api/coding/v3` 调用（OpenAI 协议兼容）；Agent Plan 使用**专属 API Key**，与本表所指的两类 API Key 均不通用，详情请参见 [快速开始](/docs/agent-plan-personal-get-started)。</blockquote> | 仅支持按量付费、Managed Agents、Coding Plan 个人版<blockquote>不支持 Coding Plan 企业版、Agent Plan 个人版及企业版。</blockquote> |
| 适用场景 | 以方舟为主，需通过 IAM 扩展调用其他云产品 | 以 IAM 用户为中心，统一管理多云凭证与权限 |

> **说明**
>
> 无论从哪个入口创建 API Key，都可通过 IAM 权限策略扩展其可访问的云产品和资源。凭证归属同一个 IAM 用户即可实现**跨产品调用**，并通过 IAM 统一管理生命周期、访问权限和操作审计。

> **注意**
>
> - IAM 控制台创建的 API Key 不在方舟 API Key 管理页面展示及管理，如需管理需在 IAM 控制台统一操作。
> - IAM 侧创建的 API Key 支持调用 Managed Agents 与 Coding Plan 个人版，不支持调用方舟的 Agent Plan 计划及 Coding Plan 企业版（Agent Plan 请使用**专属 API Key**）。
> - IAM 侧配置非预设自定义语法策略时，资源 Resource 支持写入自定义模型接入点 endpoint，不支持自定义模型 ModelID。

## 跨产品调用配置

跨产品调用的实现方式：将 API Key 归属的 IAM 用户绑定目标产品的权限策略。

> **说明**
>
> 仅支持通过 API Key 鉴权的云产品可复用同一个 API Key。TOS 仅支持 Access Key / Secret Key 或 STS 签名，不支持 API Key 鉴权；需要访问 TOS 时，请使用同一个 IAM 用户下的 AK/SK，详情请参见 [示例：使用 IAM 凭证调用方舟处理 TOS 私有文件](/docs/iam-api-key-best-practices#tos-example)。

以下两种入口任选其一：

- **方式一：IAM 控制台创建 API Key**。适合以 IAM 用户为中心统一管理多云凭证的场景。
- **方式二：方舟控制台创建 API Key + IAM 扩展权限**。适合已在方舟控制台创建 API Key，现需扩展调用其他云产品的场景。

### 方式一：IAM 控制台创建 API Key

按以下步骤为业务应用准备一个具备方舟及其他目标产品权限的 IAM 用户：

1. 登录 [IAM 用户管理](https://console.volcengine.com/iam/identitymanage/user) 页面，为业务应用创建独立 IAM 用户。
2. 为该用户绑定权限策略：
    - 火山方舟预设权限策略（如需更细粒度控制，可额外绑定方舟自定义权限策略）。
    - 其他目标云产品的权限策略（例如豆包语音等已支持 API Key 鉴权的产品）。
3. 在 IAM 控制台为该用户创建 **API Key** 类型的凭证（不是 Access Key / Secret Key），详情请参见 [API 密钥（Access Key 与 API Key）](https://docs.volcengine.com/docs/6257/64983?lang=zh)。

火山方舟预设策略与自定义策略的详细说明，详情请参见 [使用 IAM 管理权限](/docs/use-iam-to-manage-permissions)。

### 方式二：方舟控制台创建 API Key + IAM 扩展权限

按以下步骤为已有的方舟 API Key 扩展其他产品权限：

1. 在方舟控制台 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面完成 API Key 的创建。创建成功后，方舟 API Key 自动绑定 IAM 侧方舟预设权限策略。
2. 在 [IAM 用户管理](https://console.volcengine.com/iam/identitymanage/user) 页面，通过 API Key 名称搜索找到对应 IAM 用户。
3. 根据业务需要为该用户配置其他火山云产品权限策略。

## 查询 IAM API Key 用量

IAM API Key 产生的用量会纳入 [方舟控制台](https://ark.volcengine.com/region:cn-beijing/usageTracking?usageTrackingTab=model) 的全部用量汇总。以下位置均统计 IAM API Key 调用方舟的用量：

- **调用数据汇总**：全部用量 / 在线推理 / 批量推理 / 推理代工。
- **调用数据拆分**：模型 / 推理接入点（Endpoint）/ API Key。

用量归集到 Project 的规则：

- 调用**预置推理接入点**（直接通过 Model ID 调用方舟基础模型时自动使用的公共接入点，无需用户创建）：方舟为本次请求补充默认 Project 为 `default`，用量归入 `default` 项目。
- 调用**自定义推理接入点**（用户在方舟控制台创建的专属接入点，支持项目归属、标签、算力保障等能力）：用量归集到接入点所属的 Project。

推理接入点的详细说明详情请参见 [推理方式概述](/docs/deployment-overview)。

在 [调用数据拆分 - API Key 页](https://ark.volcengine.com/region:cn-beijing/usageTracking?usageTrackingTab=model)，IAM API Key 支持调用接口 [查询推理用量](/docs/get-inference-usage-api) 完成推理用量查询。调用该接口时，`Project` 参数的填写规则：

- 查询预置推理点用量：`Project` 参数填入 `default`。
- 查询对应项目下自定义推理接入点用量：填写该接入点（ep）所属的对应 `Project`。
- 查询所有项目用量：`Project` 参数留空即可。

## 使用 IAM API Key 分账

IAM API Key 对应费用支持在 [费用中心](https://console.volcengine.com/finance/bill/split-bill) 按不同维度进行分账查看。可选的分账维度：

- **按推理接入点（Endpoint）维度分账**：在 **设置分拆维度** 中选择按推理接入点维度拆分，并在分拆项中填入目标推理接入点 ID。选择该维度时，可按 Project 聚合分账。
- **按 API Key ID 维度分账**：在 **设置分拆维度** 中选择按 API Key ID 维度拆分，并在分拆项中填入 API Key ID。IAM 控制台创建的 API Key 本身不携带 Project 属性，因此不支持按 Project 聚合。

<span id="tos-example"></span>

## 示例：使用 IAM 凭证调用方舟处理 TOS 私有文件

本示例演示如何使用同一个 IAM 用户的凭证，在不公开源文件的前提下，将 TOS 私有存储桶中的视频文件传入方舟模型。示例中的两类凭证均归属于同一个 IAM 用户：

- **Access Key / Secret Key**：用于访问 TOS，生成内网预签名 URL。TOS 使用 AK/SK 签名鉴权。
- **IAM API Key**：用于调用火山方舟。方舟使用 API Key 鉴权。

> **注意**
>
> TOS 存储桶、TOS 内网域名与火山方舟服务需保持同一 Region。TOS 与火山方舟使用不同类型的凭证，不能相互替换，但可归属于同一个 IAM 用户。

### 步骤一：创建 IAM 用户并配置权限

为业务应用创建独立的 IAM 用户，并为该用户配置 TOS 与火山方舟权限（如：预设火山推理权限 `ArkInferenceFullAccess`）。

1. 登录 [IAM 用户管理](https://console.volcengine.com/iam/identitymanage/user) 页面，为业务应用创建独立 IAM 用户。
2. 为该用户绑定 TOS 与火山方舟的权限策略（火山方舟如使用预设火山推理权限 `ArkInferenceFullAccess`）。

### 步骤二：配置环境变量

配置以下环境变量，分别对应 TOS 与方舟的鉴权凭证：

```Bash
# TOS access credentials (Access Key / Secret Key)
# Fill in the AK/SK with TOS permission from the IAM console
export TOS_ACCESS_KEY="<YOUR_TOS_ACCESS_KEY>"
export TOS_SECRET_KEY="<YOUR_TOS_SECRET_KEY>"

# Volcengine Ark API Key
# Fill in the API Key bound to Ark permission in the IAM console
export ARK_API_KEY="<YOUR_IAM_API_KEY>"
```

> **说明**
>
> `ARK_API_KEY` 变量名与方舟 SDK 调用方式保持不变，只需将值填写为 IAM 控制台创建的 API Key。

### 步骤三：生成 TOS 内网预签名 URL

使用 Access Key / Secret Key 为 TOS 中的对象生成一个仅用于读取的 GET 预签名 URL。示例代码：

```Python
import os
import tos
from tos.enum import HttpMethodType

ak = os.getenv("TOS_ACCESS_KEY")
sk = os.getenv("TOS_SECRET_KEY")
# TOS internal endpoint, only cn-beijing region is supported
endpoint = "tos-cn-beijing.ivolces.com"
# Currently only cn-beijing region is supported
region = "cn-beijing"
# Replace with your bucket name
bucket_name = "<YOUR_PRIVATE_BUCKET>"
# Replace with your object key
object_key = "<PATH/TO/OBJECT.MP4>"

if not ak or not sk:
    raise ValueError("Missing TOS_ACCESS_KEY or TOS_SECRET_KEY")

client = tos.TosClientV2(ak, sk, endpoint, region)

try:
    output = client.pre_signed_url(
        HttpMethodType.Http_Method_Get,
        bucket_name,
        object_key,
        expires=3600,
    )
    print(output.signed_url)
except tos.exceptions.TosClientError as e:
    print("Client error:", e.message, e.cause)
except tos.exceptions.TosServerError as e:
    print("Server error:", e.code, e.message, e.request_id)
except Exception as e:
    print("Unknown error:", e)
```

预签名 URL 有效期可通过 `expires` 参数设置，详情请参见 [普通预签名](https://docs.volcengine.com/docs/6349/129226?lang=zh)。示例输出：

```
https://<YOUR_PRIVATE_BUCKET>.tos-cn-beijing.ivolces.com/path/to/object?...signature...
```

该 URL 仅可被华北 2（cn-beijing）Region 内的火山引擎基础设施访问（例如火山方舟），无法通过外网直接访问。

### 步骤四：使用 IAM API Key 调用方舟

将步骤三生成的预签名 URL 作为 `video_url` 传入模型，方舟 SDK 会从 `ARK_API_KEY` 环境变量读取 IAM API Key：

```Python
import os
from arkruntime import Ark

client = Ark(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

# Replace with the pre-signed URL generated in step 3
video_url = "https://<YOUR_PRIVATE_BUCKET>.tos-cn-beijing.ivolces.com/path/to/object.mp4?...signature..."

resp = client.chat.completions.create(
    # Replace with your custom endpoint ID
    model="<YOUR_CUSTOM_ENDPOINT_ID>",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请理解这个视频，输出：1. 视频主要内容 2. 关键人物 / 物体 3. 关键动作 4. 场景变化 5. 一段简短摘要",
                },
                {
                    "type": "video_url",
                    "video_url": {"url": video_url},
                },
            ],
        }
    ],
)

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

## 常见问题

### IAM API Key 可以直接配置为 ARK_API_KEY 吗

可以。请先确保该 API Key 所属的 IAM 用户已绑定适用的火山方舟权限策略。SDK 仍通过 `ARK_API_KEY` 传入凭证，鉴权参数的写法无需修改。

### IAM API Key 可以代替 TOS 的 Access Key / Secret Key 吗

不可以。TOS 使用 Access Key / Secret Key 或 STS 对请求签名，火山方舟使用 IAM API Key 鉴权。两类凭证可归属于同一个 IAM 用户，但用途不同。

### 方舟无法读取输入文件

请优先检查以下内容：

- TOS Bucket 与火山方舟服务是否属于同一 Region。
- 预签名 URL 是否已过期。
- 对象是否存在，且对象 Key 与签名时使用的值完全一致。
- URL 是否在传递过程中被截断、重复编码或丢失查询参数。
- 所选模型是否支持当前输入类型。

### 调用方舟时返回无权限

请检查以下内容：

- IAM API Key 是否属于目标 IAM 用户。
- 该用户是否已绑定适用的火山方舟权限策略。
- 策略是否允许访问当前推理接入点及其对应资源。

## 相关文档

- [管理 API Key](/docs/manage-api-keys)
- [使用 IAM 管理权限](/docs/use-iam-to-manage-permissions)
- [查询推理用量](/docs/get-inference-usage-api)