跳转到主要内容

​
文档说明

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

​
权限要求

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

​
概述

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

​
主要功能

  • 列出成员: 支持关键词搜索和游标分页，可选包含已删除成员
  • 获取成员详情: 按成员 ID 查询单个成员
  • 成员统计: 获取组织成员数量、席位使用等统计数据
  • 成员用量查询: 查询指定成员各 Quota 维度的使用情况（Plan、资源包、总计）
  • 移除成员: 将成员从组织中移除
  • Add-On Cap 管理: 设置成员个人或批量的 Shared Add-On 额度上限
  • 用量限制管理: 查询、更新、移除成员的用量限制

​
API 列表

​
1. 列出成员

GET /v1/organizations/{organization_id}/members 分页获取组织下的成员列表，支持按关键词搜索。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID

​
查询参数

参数类型必填说明
emailstring否邮箱精准查询
includeDeletedstring否设为 true 可包含已移除的成员
maxResultsinteger否每页数量（默认 20，最大 100）
nextTokenstring否分页游标

​
成功响应 (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 为空字符串表示已到最后一页。

​
响应字段说明

字段类型说明
membersarray成员列表
members[].idstring成员 ID
members[].namestring成员名称
members[].emailstring成员邮箱（可能为空）
members[].rolestring角色名称（如 org_admin、org_member）
members[].statusstring成员状态：ENABLED（正常）、DISABLED（已停用）、UNACTIVATED（未激活）、APPROVE_PENDING（待审批）、APPROVE_DECLINED（审批拒绝）、DELETED（已移除）
members[].joinedAtstring加入时间（ISO 8601）
members[].deletedAtstring 或 null删除时间（ISO 8601），未删除时不返回
maxResultsint32本次请求的每页数量
nextTokenstring下一页游标，为空表示最后一页

​
2. 获取成员详情

GET /v1/organizations/{organization_id}/members/{member_id} 获取单个成员的详细信息。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
成功响应 (200 OK)

活跃成员： 
{
  "id": "member_abc123",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2025-06-01T08:00:00Z"
}
已删除成员（**GetMember** 会自动包含已删除成员）： 
{
  "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"
}

​
响应字段说明

同「列出成员」中的 members[] 字段。

​
3. 获取成员统计

GET /v1/organizations/{organization_id}/members/statistics 获取组织成员相关的统计数据。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID

​
成功响应 (200 OK)

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

​
响应字段说明

字段类型说明
totalMembersint32总成员数
billableMembersint32计费成员数
adminMembersint32管理员数量
purchasedSeatsint32已购买席位数
remainingSeatsint32剩余席位数

​
4. 删除成员

DELETE /v1/organizations/{organization_id}/members/{member_id} 将成员从组织中移除。移除前会检查成员在当前计费周期内是否有使用量。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
成功响应 (200 OK)

成员在本周期有使用量（席位释放需等到周期结束）： 
{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}
成员在本周期无使用量（席位可立即释放）： 
{
  "id": "member_abc123",
  "hasBillingCycleUsage": false
}

​
响应字段说明

字段类型说明
idstring被删除成员的 ID
hasBillingCycleUsagebool该成员在当前计费周期内是否有使用量（影响席位释放时间）

​
错误响应

成员不属于该团队 (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 配额、资源包配额、总计配额和组织共享包配额。当前固定查询 big_model_credits 维度。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
成功响应 (200 OK)

有组织共享包、状态正常： 
{
  "userId": "user_abc123",
  "quotaKey": "big_model_credits",
  "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"
}
无组织共享包、用量已超限： 
{
  "userId": "user_def456",
  "quotaKey": "big_model_credits",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "restricted"
}
当组织没有共享包时 sharedQuota 不返回；当成员没有资源包时 resourcePackageQuota 不返回。status 为 restricted 表示用量已达上限。

​
响应字段说明

字段类型说明
userIdstring用户 ID
quotaKeystring配额维度 Key
planQuotaobjectPlan 配额信息
resourcePackageQuotaobject资源包配额信息
totalQuotaobject总计配额信息（Plan + 资源包）
sharedQuotaobject 或 null组织共享包配额信息（如果成员所在组织无共享包，则该字段不返回）
lastResetAtstring上次重置时间（ISO 8601）
nextResetAtstring下次重置时间（ISO 8601）
statusstring用户状态：active 或 restricted
Quota Summary 字段说明
字段类型说明
usedValuefloat64已使用量
limitValuefloat64配额上限
unitstring单位（如 credits）

​
6. 更新成员 Add-On Cap

PUT /v1/organizations/{organization_id}/members/{member_id}/addon-cap 更新成员的 Shared Add-On 额度上限（基于 Big Model Credits 配额）。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
请求参数 (JSON)

字段类型必填校验规则说明
addOnCapint64 或 null是非负整数或 null额度上限，null 表示不限制，0 表示禁用

​
请求示例

设置额度上限： 
{
  "addOnCap": 1000
}
设置为不限制： 
{
  "addOnCap": null
}

​
成功响应 (200 OK)

{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": 1000
}
不限制时： 
{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": null
}

​
响应字段说明

字段类型说明
memberIdstring成员 ID
emailstring成员邮箱
addOnCapint64 或 null当前额度上限，null 表示不限制

​
错误响应

addOnCap 格式无效 (400) 
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
成员不属于该团队 (404) 
{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}

​
7. 批量更新成员 Add-On Cap

POST /v1/organizations/{organization_id}/batchUpdateAddOnCap 批量更新指定成员的 Shared Add-On 额度上限（基于 Big Model Credits 配额）。单次请求最多 100 个成员，所有成员设置为相同的额度上限。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID

​
请求参数 (JSON)

字段类型必填校验规则说明
addOnCapint64 或 null是非负整数或 null额度上限，null 表示不限制，0 表示禁用
memberIdsstring[]是1～100 个非空字符串需要更新的成员 ID 列表

​
请求示例

批量设置额度上限： 
{
  "addOnCap": 1000,
  "memberIds": ["member_abc123", "member_def456"]
}
批量设置为不限制： 
{
  "addOnCap": null,
  "memberIds": ["member_abc123"]
}

​
成功响应 (200 OK)

{
  "members": [
    {
      "memberId": "member_abc123",
      "previousAddOnCap": 500
    },
    {
      "memberId": "member_def456",
      "previousAddOnCap": null
    }
  ]
}
previousAddOnCap 为 null 表示该成员之前未设置限制（无限制）。

​
响应字段说明

字段类型说明
membersarray更新结果列表，与请求中 memberIds 顺序一致
members[].memberIdstring成员 ID
members[].previousAddOnCapint64 或 null更新前的额度上限，null 表示之前未设置限制

​
错误响应

addOnCap 格式无效 (400) 
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
memberIds 为空 (400) 
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not be empty"
}
memberIds 超过 100 个 (400) 
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not exceed 100"
}

​
8. 获取成员用量限制

GET /v1/organizations/{organization_id}/members/{member_id}/usage-limits/{quota_key} 查询指定成员在某个 Quota Key 下的用量限制配置。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID
quota_keystring是配额维度 Key（如 big_model_credits）

​
成功响应 (200 OK)

限制已启用： 
{
  "id": "limit_abc123",
  "organizationId": "org_xxx",
  "userId": "user_abc123",
  "quotaKey": "big_model_credits",
  "limitValue": 1000.0,
  "usedValue": 350.5,
  "resetCycle": "monthly",
  "isActive": true,
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z"
}
限制已暂停（**isActive: false**）： 
{
  "id": "limit_abc123",
  "organizationId": "org_xxx",
  "userId": "user_abc123",
  "quotaKey": "big_model_credits",
  "limitValue": 1000.0,
  "usedValue": 350.5,
  "resetCycle": "monthly",
  "isActive": false,
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z"
}
isActive 为 false 时限制规则不生效，但记录仍然保留，可随时重新启用。

​
响应字段说明

字段类型说明
idstring用量限制记录 ID
organizationIdstring组织 ID
userIdstring用户 ID
quotaKeystring配额维度 Key
limitValuefloat64用量上限值
usedValuefloat64已使用量
resetCyclestring重置周期（如 monthly）
isActivebool是否启用
lastResetAtstring上次重置时间（ISO 8601）
nextResetAtstring下次重置时间（ISO 8601）

​
9. 更新成员用量限制

PUT /v1/organizations/{organization_id}/members/{member_id}/usage-limits/{quota_key} 更新指定成员在某个 Quota Key 下的用量限制。如果该限制不存在，则自动创建。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID
quota_keystring是配额维度 Key（如 big_model_credits）

​
请求参数 (JSON)

字段类型必填说明
limitValuefloat64是用量上限值
resetCyclestring否重置周期（如 monthly）
isActivebool否是否启用

​
请求示例

创建或更新完整限制： 
{
  "limitValue": 1000.0,
  "resetCycle": "monthly",
  "isActive": true
}
仅调整上限值（保留已有 resetCycle 和 isActive）： 
{
  "limitValue": 2000.0
}
暂停限制（不修改上限）： 
{
  "limitValue": 1000.0,
  "isActive": false
}

​
成功响应 (200 OK)

同「获取成员用量限制」的响应格式。

​
10. 设置成员用量无限制

DELETE /v1/organizations/{organization_id}/members/{member_id}/usage-limits/{quota_key} 移除指定成员在某个 Quota Key 下的用量限制，恢复为无限制状态。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID
quota_keystring是配额维度 Key（如 big_model_credits）

​
成功响应 (200 OK)

同「获取成员用量限制」的响应格式。

​
错误码

错误码HTTP 状态码说明
BadRequest400请求参数无效（如 member_id 为空、addOnCap 为负数）
InvalidAddOnCapFormat400addOnCap 格式无效
InsufficientMembers400组织成员数量不能低于最低要求
Unauthorized401API Key 缺失或无效
Forbidden403无权限访问该组织
NotFound404成员不存在
UserNotTeamMember404用户不是该团队的成员
InternalError500服务器内部错误
错误响应结构见 约定与规范 中的「错误响应」一节。

​
使用示例

​
列出成员

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

​
按邮箱精准搜索成员

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

​
列出成员（包含已移除）

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

​
获取成员详情

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

​
获取成员统计

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

​
删除成员

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

​
更新成员 Add-On Cap

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

​
获取成员用量

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

​
批量更新成员 Add-On Cap

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

​
获取成员用量限制

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

​
更新成员用量限制

curl -X PUT "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-limits/big_model_credits" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "limitValue": 1000.0,
    "resetCycle": "monthly",
    "isActive": true
  }'

​
设置成员用量无限制

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