AI 助理
文档备案控制台
官方文档
首页

成员 API

更新时间：
复制 MD 格式
产品详情
我的收藏

列出与查询组织成员、统计、配额与 Add-On Cap 等接口说明。

文档说明

本文面向需在组织外系统化管理成员与配额的集成方。调用前请完成 获取 API Key，并阅读 约定与规范。

权限要求

  • 使用有效的 API Key（Authorization: Bearer）。

  • API Key 必须属于目标组织，且调用者权限需覆盖相应操作（以产品为准）。

概述

成员管理 API 提供组织成员的查询、统计、用量查看、移除以及 Add-On Cap 管理功能。所有接口通过 API Key 进行鉴权，需将 Key 对应到目标组织。

主要功能

  • 列出成员: 支持关键词搜索和游标分页，可选包含已删除成员

  • 获取成员详情: 按成员 ID 查询单个成员

  • 成员统计: 获取组织成员数量、席位使用等统计数据

  • 成员用量查询: 查询单个或批量成员的额度与使用情况（Plan、资源包、总计）

  • 移除成员: 将成员从组织中移除

  • Add-On Cap 管理: 设置成员个人或批量的 Shared Add-On 额度上限

API 列表

1. 列出成员

GET /v1/organizations/{organization_id}/members

分页获取组织下的成员列表，支持按关键词搜索。

路径参数

参数

类型

必填

说明

organization_id

string

是

组织 ID

查询参数

参数

类型

必填

说明

email

string

否

邮箱精准查询

includeDeleted

string

否

设为 true 可包含已移除的成员

maxResults

integer

否

每页数量（默认 20，最大 100）

nextToken

string

否

分页游标

成功响应 (200 OK)

默认查询（仅活跃成员）：

{
  "members": [
    {
      "id": "member_abc123",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_ghi789",
      "name": "王五",
      "role": "org_member",
      "status": "ENABLED",
      "joinedAt": "2025-07-10T14:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

部分成员记录可能不返回 email 字段，集成时请按可选字段处理。

包含已删除成员（includeDeleted=true）：

{
  "members": [
    {
      "id": "member_abc123",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_def456",
      "name": "李四",
      "email": "lisi@example.com",
      "role": "org_member",
      "status": "DELETED",
      "joinedAt": "2025-03-15T10:00:00Z",
      "deletedAt": "2026-02-01T12:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

deletedAt 仅在成员已被删除时返回，活跃成员不包含此字段。nextToken 为空字符串表示已到最后一页。

响应字段说明

字段

类型

说明

members

array

成员列表

members[].id

string

成员 ID

members[].name

string

成员名称

members[].email

string

成员邮箱（可能为空）

members[].role

string

角色名称（如 org_admin、org_member）

members[].status

string

成员状态：ENABLED（正常）、DISABLED（已停用）、UNACTIVATED（未激活）、APPROVE_PENDING（待审批）、APPROVE_DECLINED（审批拒绝）、DELETED（已移除）

members[].joinedAt

string

加入时间（ISO 8601）

members[].deletedAt

string 或 null

删除时间（ISO 8601），未删除时不返回

maxResults

int32

本次请求的每页数量

nextToken

string

下一页游标，为空表示最后一页

2. 获取成员详情

GET /v1/organizations/{organization_id}/members/{member_id}

获取单个成员的详细信息。

路径参数

参数

类型

必填

说明

organization_id

string

是

组织 ID

member_id

string

是

成员 ID

成功响应 (200 OK)

{
  "id": "member_abc123",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2025-06-01T08:00:00Z"
}

响应字段说明同「列出成员」中的 members[] 字段。

3. 获取成员统计

GET /v1/organizations/{organization_id}/members/statistics

获取组织成员相关的统计数据。

路径参数

参数

类型

必填

说明

organization_id

string

是

组织 ID

成功响应 (200 OK)

{
  "totalMembers": 50,
  "billableMembers": 45,
  "adminMembers": 3,
  "purchasedSeats": 100,
  "remainingSeats": 55
}

响应字段说明

字段

类型

说明

totalMembers

int32

总成员数

billableMembers

int32

计费成员数

adminMembers

int32

管理员数量

purchasedSeats

int32

已购买席位数

remainingSeats

int32

剩余席位数

4. 删除成员

DELETE /v1/organizations/{organization_id}/members/{member_id}

将成员从组织中移除。移除前会检查成员在当前计费周期内是否有使用量。

路径参数

参数

类型

必填

说明

organization_id

string

是

组织 ID

member_id

string

是

成员 ID

成功响应 (200 OK)

{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}

响应字段说明

字段

类型

说明

id

string

被删除成员的 ID

hasBillingCycleUsage

bool

该成员在当前计费周期内是否有使用量（影响席位释放时间）

错误响应

成员不属于该团队 (404)：

{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}

成员数量不足 (400)：

{
  "requestId": "req_abc123",
  "code": "InsufficientMembers",
  "message": "The number of organization members cannot be less than the minimum requirement"
}

5. 获取成员用量

GET /v1/organizations/{organization_id}/members/{member_id}/quota

查询指定成员的完整使用情况，包括 Plan 配额、资源包配额、总计配额和组织共享包配额。

路径参数

参数

类型

必填

说明

organization_id

string

是

组织 ID

member_id

string

是

成员 ID

成功响应 (200 OK)

{
  "userId": "user_abc123",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 350.5,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "resourcePackageQuota": {
    "quotaSummary": {
      "usedValue": 100.0,
      "limitValue": 500.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 450.5,
      "limitValue": 1500.0,
      "unit": "credits"
    }
  },
  "sharedQuota": {
    "quotaSummary": {
      "usedValue": 200.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "active"
}

当组织没有共享包时 sharedQuota 不返回；当成员没有资源包时 resourcePackageQuota 不返回。status 为 restricted 表示用量已达上限。

响应字段说明

字段

类型

说明

userId

string

用户 ID

planQuota

object

Plan 配额信息

resourcePackageQuota

object

资源包配额信息

totalQuota

object

总计配额信息（Plan + 资源包）

sharedQuota

object 或 null

组织共享包配额信息（如果成员所在组织无共享包，则该字段不返回）

lastResetAt

string

上次重置时间（ISO 8601）

nextResetAt

string

下次重置时间（ISO 8601）

status

string

用户状态：active 或 restricted

6. 批量获取成员用量

POST /v1/organizations/{organization_id}/members/batchGetQuota

一次查询多个成员的额度与使用情况。

请求体（JSON）

字段

类型

必填

校验规则

说明

memberIds

string[]

是

1–100 个非空成员 ID

需要查询用量的成员列表

{
  "memberIds": ["member_abc123", "member_def456"]
}

成功响应（200 OK）

{
  "quotas": [
    {
      "memberId": "member_abc123",
      "userId": "user_abc123",
      "planQuota": {
        "quotaSummary": {
          "usedValue": 350.5,
          "limitValue": 1000.0,
          "unit": "credits"
        }
      },
      "totalQuota": {
        "quotaSummary": {
          "usedValue": 450.5,
          "limitValue": 1500.0,
          "unit": "credits"
        }
      },
      "lastResetAt": "2026-03-01T00:00:00Z",
      "nextResetAt": "2026-04-01T00:00:00Z",
      "status": "active"
    },
    {
      "memberId": "member_def456",
      "userId": "user_def456"
    }
  ]
}

quotas 数组与 memberIds 的顺序一致，重复的成员 ID 也会按原顺序返回。成员没有额度记录时，该项仅返回 memberId 和 userId。只要有任一成员不属于该组织，整个请求返回 404 NotFound，不会部分成功。

7. 更新成员 Add-On Cap

PUT /v1/organizations/{organization_id}/members/{member_id}/addon-cap

更新成员的 Shared Add-On 额度上限（基于 Big Model Credits 配额）。

请求参数 (JSON)

字段

类型

必填

校验规则

说明

addOnCap

int64 或 null

是

非负整数或 null

额度上限，null 表示不限制，0 表示禁用

成功响应 (200 OK)

{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": 1000
}

响应字段说明

字段

类型

说明

memberId

string

成员 ID

email

string

成员邮箱

addOnCap

int64 或 null

当前额度上限，null 表示不限制

8. 批量更新成员 Add-On Cap

POST /v1/organizations/{organization_id}/batchUpdateAddOnCap

批量更新指定成员的 Shared Add-On 额度上限。单次请求最多 100 个成员，所有成员设置为相同的额度上限。

请求参数 (JSON)

字段

类型

必填

校验规则

说明

addOnCap

int64 或 null

是

非负整数或 null

额度上限，null 表示不限制，0 表示禁用

memberIds

string[]

是

1～100 个非空字符串

需要更新的成员 ID 列表

成功响应 (200 OK)

{
  "members": [
    {
      "memberId": "member_abc123",
      "previousAddOnCap": 500
    },
    {
      "memberId": "member_def456",
      "previousAddOnCap": null
    }
  ]
}

previousAddOnCap 为 null 表示该成员之前未设置限制（无限制）。

错误码

错误码

HTTP 状态码

说明

BadRequest

400

请求参数无效

InvalidBatchQuotaRequest

400

批量用量查询的 JSON 请求体格式无效

InvalidAddOnCapFormat

400

addOnCap 格式无效

InsufficientMembers

400

组织成员数量不能低于最低要求

Unauthorized

401

API Key 缺失或无效

Forbidden

403

无权限访问该组织

NotFound

404

成员不存在

UserNotTeamMember

404

用户不是该团队的成员

InternalError

500

服务器内部错误

错误响应结构见 约定与规范 中的「错误响应」一节。

使用示例

列出成员

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members?maxResults=20" \
  -H "Authorization: Bearer <api_key>"

按邮箱精准搜索成员

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members?email=zhangsan@example.com" \
  -H "Authorization: Bearer <api_key>"

获取成员详情

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"

获取成员统计

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/statistics" \
  -H "Authorization: Bearer <api_key>"

删除成员

curl -X DELETE "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"

获取成员用量

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_abc123/quota" \
  -H "Authorization: Bearer <api_key>"

批量获取成员用量

curl -X POST "https://api.qoder.com.cn/v1/organizations/org_xxx/members/batchGetQuota" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": ["member_abc123", "member_def456"]
  }'

更新成员 Add-On Cap

curl -X PUT "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_abc123/addon-cap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000
  }'

批量更新成员 Add-On Cap

curl -X POST "https://api.qoder.com.cn/v1/organizations/org_xxx/batchUpdateAddOnCap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000,
    "memberIds": ["member_abc123", "member_def456"]
  }'
上一篇：API 密钥安全下一篇：用量 API