OpenAI 管理 API

管理 API（Admin APIs）可自动执行组织管理工作，包括邀请用户、查看审计日志、管理项目和 API 密钥、设置支出上限与提醒、数据保留及速率限制，适合在控制台之外运行的后台自动化、安全流程与运维工具。

管理凭据、用户所属的项目密钥与工作负载的服务账号各有适用场景，见 API 密钥和服务账号。

端点详情见管理接口参考，包括管理密钥、邀请、用户、项目、支出上限及审计日志。

在 SDK 中使用管理 API 密钥

访问这些端点前，先创建 Admin API 密钥。管理密钥不能用于非管理端点。

以下 SDK 版本开始支持管理 API，必要时升级：Node 6.36.0、Python 2.34.0、Go 3.34.0、Ruby 0.61.0、Java 4.34.0。设置 OPENAI_ADMIN_KEY，再初始化对应语言的 SDK：

来源示例 1（javascript）：

// [中文] 仅使用OPENAI_ADMIN_KEY初始化管理客户端；Admin密钥不能用于普通推理端点。
import OpenAI from "openai";

const client = new OpenAI({
  adminAPIKey: process.env.OPENAI_ADMIN_KEY,
});

来源示例 2（python）：

## [中文] 仅使用OPENAI_ADMIN_KEY初始化管理客户端；Admin密钥不能用于普通推理端点。
import os
from openai import OpenAI

client = OpenAI(
    admin_api_key=os.environ["OPENAI_ADMIN_KEY"],
)

来源示例 3（go）：

// [中文] 仅使用OPENAI_ADMIN_KEY初始化管理客户端；Admin密钥不能用于普通推理端点。
package main

import (
    "os"

    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/option"
)

func main() {
    client := openai.NewClient(
        option.WithAdminAPIKey(os.Getenv("OPENAI_ADMIN_KEY")),
    )

    _ = client
}

来源示例 4（java）：

// [中文] 仅使用OPENAI_ADMIN_KEY初始化管理客户端；Admin密钥不能用于普通推理端点。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client =
    OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();

来源示例 5（ruby）：

## [中文] 仅使用OPENAI_ADMIN_KEY初始化管理客户端；Admin密钥不能用于普通推理端点。
require "openai"

openai = OpenAI::Client.new(
  admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")
)

限制项目的模型访问

项目模型权限可配置允许列表或拒绝列表。mode: allow_list 仅允许所列模型；mode: deny_list 阻止所列模型，允许其他可用模型。模型 ID 必须对组织可见，包括可见的微调模型快照。

来源示例 6（javascript）：

// [中文] 设置项目模型允许/拒绝列表；allow_list只允许所列模型，deny_list仅阻止所列模型。
const modelPermissions =
  await client.admin.organization.projects.modelPermissions.update("proj_abc", {
    mode: "allow_list",
    model_ids: ["gpt-4.1", "o3"],
  });

console.log(modelPermissions.mode);

来源示例 7（python）：

## [中文] 设置项目模型允许/拒绝列表；allow_list只允许所列模型，deny_list仅阻止所列模型。
model_permissions = client.admin.organization.projects.model_permissions.update(
    "proj_abc",
    mode="allow_list",
    model_ids=["gpt-4.1", "o3"],
)

print(model_permissions.mode)

来源示例 8（go）：

// [中文] 设置项目模型允许/拒绝列表；allow_list只允许所列模型，deny_list仅阻止所列模型。
ctx := context.Background()

modelPermissions, err := client.Admin.Organization.Projects.ModelPermissions.Update(
    ctx,
    "proj_abc",
    openai.AdminOrganizationProjectModelPermissionUpdateParams{
        Mode:     openai.AdminOrganizationProjectModelPermissionUpdateParamsModeAllowList,
        ModelIDs: []string{"gpt-4.1", "o3"},
    },
)
if err != nil {
    panic(err)
}

fmt.Println(modelPermissions.Mode)

来源示例 9（java）：

// [中文] 设置项目模型允许/拒绝列表；allow_list只允许所列模型，deny_list仅阻止所列模型。
import com.openai.models.admin.organization.projects.modelpermissions.ModelPermissionUpdateParams;
import com.openai.models.admin.organization.projects.modelpermissions.ProjectModelPermissions;
import java.util.List;

ProjectModelPermissions modelPermissions =
    client
        .admin()
        .organization()
        .projects()
        .modelPermissions()
        .update(
            "proj_abc",
            ModelPermissionUpdateParams.builder()
                .mode(ModelPermissionUpdateParams.Mode.ALLOW_LIST)
                .modelIds(List.of("gpt-4.1", "o3"))
                .build());

System.out.println(modelPermissions.mode());

来源示例 10（ruby）：

## [中文] 设置项目模型允许/拒绝列表；allow_list只允许所列模型，deny_list仅阻止所列模型。
model_permissions = openai.admin.organization.projects.model_permissions.update(
  "proj_abc",
  mode: :allow_list,
  model_ids: ["gpt-4.1", "o3"]
)

puts(model_permissions.mode)

设置组织支出上限

通过支出上限端点创建或替换组织的月度硬支出上限，threshold_amount 以美分为单位。下例设置每月 100 美元：

来源示例 11（bash）：

## [中文] 组织月度硬支出上限以美分计；此处10000美分为100美元，达到上限的受影响请求返回429。
curl -X POST https://api.openai.com/v1/organization/spend_limit \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold_amount": 10000,
    "currency": "USD",
    "interval": "month"
  }'

已跟踪支出达到硬上限后，受影响请求返回 429。详情见支出限制指南。

管理支出提醒

项目支出达到阈值时，可通过项目提醒通知团队，阈值同样以美分为单位。创建提醒：

来源示例 12（javascript）：

// [中文] 创建项目支出提醒，金额以美分计；提醒与阻止请求的硬上限不同，收件地址是示例。
const spendAlert = await client.admin.organization.projects.spendAlerts.create(
  "proj_abc",
  {
    currency: "USD",
    interval: "month",
    notification_channel: {
      recipients: ["billing@example.com"],
      type: "email",
      subject_prefix: "OpenAI spend",
    },
    threshold_amount: 50000,
  }
);

console.log(spendAlert.id);

来源示例 13（python）：

## [中文] 创建项目支出提醒，金额以美分计；提醒与阻止请求的硬上限不同，收件地址是示例。
spend_alert = client.admin.organization.projects.spend_alerts.create(
    "proj_abc",
    currency="USD",
    interval="month",
    notification_channel={
        "recipients": ["billing@example.com"],
        "type": "email",
        "subject_prefix": "OpenAI spend",
    },
    threshold_amount=50000,
)

print(spend_alert.id)

来源示例 14（go）：

// [中文] 创建项目支出提醒，金额以美分计；提醒与阻止请求的硬上限不同，收件地址是示例。
ctx := context.Background()

spendAlert, err := client.Admin.Organization.Projects.SpendAlerts.New(
    ctx,
    "proj_abc",
    openai.AdminOrganizationProjectSpendAlertNewParams{
        Currency: openai.AdminOrganizationProjectSpendAlertNewParamsCurrencyUsd,
        Interval: openai.AdminOrganizationProjectSpendAlertNewParamsIntervalMonth,
        NotificationChannel: openai.AdminOrganizationProjectSpendAlertNewParamsNotificationChannel{
            Recipients:    []string{"billing@example.com"},
            Type:          "email",
            SubjectPrefix: openai.String("OpenAI spend"),
        },
        ThresholdAmount: 50000,
    },
)
if err != nil {
    panic(err)
}

fmt.Println(spendAlert.ID)

来源示例 15（java）：

// [中文] 创建项目支出提醒，金额以美分计；提醒与阻止请求的硬上限不同，收件地址是示例。
import com.openai.models.admin.organization.projects.spendalerts.ProjectSpendAlert;
import com.openai.models.admin.organization.projects.spendalerts.SpendAlertCreateParams;

ProjectSpendAlert spendAlert =
    client
        .admin()
        .organization()
        .projects()
        .spendAlerts()
        .create(
            "proj_abc",
            SpendAlertCreateParams.builder()
                .currency(SpendAlertCreateParams.Currency.USD)
                .interval(SpendAlertCreateParams.Interval.MONTH)
                .notificationChannel(
                    SpendAlertCreateParams.NotificationChannel.builder()
                        .addRecipient("billing@example.com")
                        .subjectPrefix("OpenAI spend")
                        .build())
                .thresholdAmount(50000L)
                .build());

System.out.println(spendAlert.id());

来源示例 16（ruby）：

## [中文] 创建项目支出提醒，金额以美分计；提醒与阻止请求的硬上限不同，收件地址是示例。
spend_alert = openai.admin.organization.projects.spend_alerts.create(
  "proj_abc",
  currency: :USD,
  interval: :month,
  notification_channel: {
    recipients: ["billing@example.com"],
    type: :email,
    subject_prefix: "OpenAI spend"
  },
  threshold_amount: 50_000
)

puts(spend_alert.id)

管理数据保留

项目数据保留控制可覆盖或继承组织政策。设 retention_type: organization_default 继承组织设置：

来源示例 17（javascript）：

// [中文] 为项目设置数据保留；organization_default表示继承组织政策，不代表自动获得ZDR批准。
const dataRetention =
  await client.admin.organization.projects.dataRetention.update("proj_abc", {
    retention_type: "organization_default",
  });

console.log(dataRetention.type);

来源示例 18（python）：

## [中文] 为项目设置数据保留；organization_default表示继承组织政策，不代表自动获得ZDR批准。
data_retention = client.admin.organization.projects.data_retention.update(
    "proj_abc",
    retention_type="organization_default",
)

print(data_retention.type)

来源示例 19（go）：

// [中文] 为项目设置数据保留；organization_default表示继承组织政策，不代表自动获得ZDR批准。
ctx := context.Background()

dataRetention, err := client.Admin.Organization.Projects.DataRetention.Update(
    ctx,
    "proj_abc",
    openai.AdminOrganizationProjectDataRetentionUpdateParams{
        RetentionType: openai.AdminOrganizationProjectDataRetentionUpdateParamsRetentionTypeOrganizationDefault,
    },
)
if err != nil {
    panic(err)
}

println(dataRetention.Type)

来源示例 20（java）：

// [中文] 为项目设置数据保留；organization_default表示继承组织政策，不代表自动获得ZDR批准。
import com.openai.models.admin.organization.projects.dataretention.DataRetentionUpdateParams;
import com.openai.models.admin.organization.projects.dataretention.ProjectDataRetention;

ProjectDataRetention dataRetention =
    client
        .admin()
        .organization()
        .projects()
        .dataRetention()
        .update(
            "proj_abc",
            DataRetentionUpdateParams.builder()
                .retentionType(DataRetentionUpdateParams.RetentionType.ORGANIZATION_DEFAULT)
                .build());

System.out.println(dataRetention.type());

来源示例 21（ruby）：

## [中文] 为项目设置数据保留；organization_default表示继承组织政策，不代表自动获得ZDR批准。
data_retention = openai.admin.organization.projects.data_retention.update(
  "proj_abc",
  retention_type: :organization_default
)

puts(data_retention.type)

通过邮箱邀请用户

通过 Invites 端点向指定邮箱发送加入组织的邀请：

来源示例 22（javascript）：

// [中文] 向示例邮箱发送组织邀请的来源代码；实际执行前须替换地址并确认目标组织与邀请范围。
const invite = await client.admin.organization.invites.create({
  email: "user@example.com",
  role: "reader",
});

console.log(invite.id);

来源示例 23（python）：

## [中文] 向示例邮箱发送组织邀请的来源代码；实际执行前须替换地址并确认目标组织与邀请范围。
invite = client.admin.organization.invites.create(
    email="user@example.com",
    role="reader",
)

print(invite.id)

来源示例 24（go）：

// [中文] 向示例邮箱发送组织邀请的来源代码；实际执行前须替换地址并确认目标组织与邀请范围。
ctx := context.Background()

invite, err := client.Admin.Organization.Invites.New(ctx, openai.AdminOrganizationInviteNewParams{
    Email: "user@example.com",
    Role:  openai.AdminOrganizationInviteNewParamsRoleReader,
})
if err != nil {
    panic(err)
}

fmt.Println(invite.ID)

来源示例 25（java）：

// [中文] 向示例邮箱发送组织邀请的来源代码；实际执行前须替换地址并确认目标组织与邀请范围。
import com.openai.models.admin.organization.invites.Invite;
import com.openai.models.admin.organization.invites.InviteCreateParams;

Invite invite =
    client
        .admin()
        .organization()
        .invites()
        .create(
            InviteCreateParams.builder()
                .email("user@example.com")
                .role(InviteCreateParams.Role.READER)
                .build());

System.out.println(invite.id());

来源示例 26（ruby）：

## [中文] 向示例邮箱发送组织邀请的来源代码；实际执行前须替换地址并确认目标组织与邀请范围。
invite = openai.admin.organization.invites.create(
  email: "user@example.com",
  role: :reader
)

puts(invite.id)

检索审计日志

通过 Audit Logs 端点列出组织近期的用户操作和配置变更：

来源示例 27（javascript）：

// [中文] 通过管理客户端读取组织审计记录；只读返回近期用户操作和配置变化。
const auditLogs = await client.admin.organization.auditLogs.list({
  limit: 10,
});

console.log(auditLogs.data);

来源示例 28（python）：

## [中文] 通过管理客户端读取组织审计记录；只读返回近期用户操作和配置变化。
audit_logs = client.admin.organization.audit_logs.list(limit=10)

for audit_log in audit_logs.data:
    print(audit_log.id)

来源示例 29（go）：

// [中文] 通过管理客户端读取组织审计记录；只读返回近期用户操作和配置变化。
ctx := context.Background()

auditLogs, err := client.Admin.Organization.AuditLogs.List(ctx, openai.AdminOrganizationAuditLogListParams{
    Limit: openai.Int(10),
})
if err != nil {
    panic(err)
}

for _, auditLog := range auditLogs.Data {
    fmt.Println(auditLog.ID)
}

来源示例 30（java）：

// [中文] 通过管理客户端读取组织审计记录；只读返回近期用户操作和配置变化。
import com.openai.models.admin.organization.auditlogs.AuditLogListParams;

var page =
    client
        .admin()
        .organization()
        .auditLogs()
        .list(AuditLogListParams.builder().limit(10L).build());

page.data().forEach(auditLog -> System.out.println(auditLog.id()));

来源示例 31（ruby）：

## [中文] 通过管理客户端读取组织审计记录；只读返回近期用户操作和配置变化。
audit_logs = openai.admin.organization.audit_logs.list(limit: 10)

(audit_logs.data || []).each do |audit_log|
  puts(audit_log.id)
end