You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

请输入
  • 文档首页
    • 火山方舟权限管理IAM API Key 最佳实践
复制全文
下载 pdf
我的收藏
权限管理
IAM API Key 最佳实践
复制全文
下载 pdf
我的收藏
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 控制台创建的 API Key​
创建入口​
方舟控制台 API Key 管理 页面​
IAM 控制台​
管理入口​
方舟控制台 + IAM 控制台​
仅 IAM 控制台​
IAM 控制台创建的 API Key 不在方舟 API Key 管理 页面展示。​
默认权限​
自动绑定方舟预设权限策略，具备方舟访问权限​
需手动为所属 IAM 用户绑定方舟权限策略​
扩展其他云产品权限​
通过 IAM 用户管理为 API Key 添加其他产品权限策略​
通过 IAM 用户绑定其他产品权限策略​
支持的方舟订阅​
支持全部方舟订阅​
按量付费、Coding Plan 使用普通方舟 API Key，其中 Coding Plan 需切换到专属 Base URL https://ark.cn-beijing.volces.com/api/coding/v3 调用（OpenAI 协议兼容）；Agent Plan 使用专属 API Key，与本表所指的两类 API Key 均不通用，详情请参见 快速开始。​
仅支持按量付费、Managed Agents、Coding Plan 个人版​
不支持 Coding Plan 企业版、Agent Plan 个人版及企业版。​
适用场景​
以方舟为主，需通过 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 私有文件。​
以下两种入口任选其一：​
  • 方式一：IAM 控制台创建 API Key。适合以 IAM 用户为中心统一管理多云凭证的场景。​
  • 方式二：方舟控制台创建 API Key + IAM 扩展权限。适合已在方舟控制台创建 API Key，现需扩展调用其他云产品的场景。​
方式一：IAM 控制台创建 API Key​
按以下步骤为业务应用准备一个具备方舟及其他目标产品权限的 IAM 用户：​
  1. 登录 IAM 用户管理 页面，为业务应用创建独立 IAM 用户。​
  1. 为该用户绑定权限策略：​
  • 火山方舟预设权限策略（如需更细粒度控制，可额外绑定方舟自定义权限策略）。​
  • 其他目标云产品的权限策略（例如豆包语音等已支持 API Key 鉴权的产品）。​
  1. 在 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 侧方舟预设权限策略。​
  1. 在 IAM 用户管理 页面，通过 API Key 名称搜索找到对应 IAM 用户。​
  1. 根据业务需要为该用户配置其他火山云产品权限策略。​
查询 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 鉴权。​
注意​
TOS 存储桶、TOS 内网域名与火山方舟服务需保持同一 Region。TOS 与火山方舟使用不同类型的凭证，不能相互替换，但可归属于同一个 IAM 用户。​
步骤一：创建 IAM 用户并配置权限​
为业务应用创建独立的 IAM 用户，并为该用户配置 TOS 与火山方舟权限（如：预设火山推理权限 ArkInferenceFullAccess）。​
  1. 登录 IAM 用户管理 页面，为业务应用创建独立 IAM 用户。​
  1. 为该用户绑定 TOS 与火山方舟的权限策略（火山方舟如使用预设火山推理权限 ArkInferenceFullAccess）。​
步骤二：配置环境变量​
配置以下环境变量，分别对应 TOS 与方舟的鉴权凭证：​
​
# 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。示例代码：​
​
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://<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：​
​
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 用户。​
  • 该用户是否已绑定适用的火山方舟权限策略。​
  • 策略是否允许访问当前推理接入点及其对应资源。​
相关文档​
​
最近更新时间：2026.11.03 15:22:53
这个页面对您有帮助吗？
有用
有用
无用
无用