IAM API Key 最佳实践

火山方舟部分模型服务已可使用 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 管理权限。

方舟 API Key 与 IAM API Key 对比#

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

跨产品调用配置#

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

以下两种入口任选其一：

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

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

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

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

火山方舟预设策略与自定义策略的详细说明，详情请参见 使用 IAM 管理权限。

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

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

1. 在方舟控制台 API Key 管理 页面完成 API Key 的创建。创建成功后，方舟 API Key 自动绑定 IAM 侧方舟预设权限策略。
2. 在 IAM 用户管理 页面，通过 API Key 名称搜索找到对应 IAM 用户。
3. 根据业务需要为该用户配置其他火山云产品权限策略。

查询 IAM API Key 用量#

IAM API Key 产生的用量会纳入 方舟控制台 的全部用量汇总。以下位置均统计 IAM API Key 调用方舟的用量：

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

用量归集到 Project 的规则：

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

推理接入点的详细说明详情请参见 推理方式概述。

在 调用数据拆分 - API Key 页，IAM API Key 支持调用接口 查询推理用量 完成推理用量查询。调用该接口时，Project 参数的填写规则：

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

使用 IAM API Key 分账#

IAM API Key 对应费用支持在 费用中心 按不同维度进行分账查看。可选的分账维度：

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

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

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

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

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

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

1. 登录 IAM 用户管理 页面，为业务应用创建独立 IAM 用户。
2. 为该用户绑定 TOS 与火山方舟的权限策略（火山方舟如使用预设火山推理权限 ArkInferenceFullAccess）。

步骤二：配置环境变量#

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

1
2
3
4
5
6
7
8# 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>"

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import 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://<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：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import 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
• 使用 IAM 管理权限
• 查询推理用量