OpenAI 费用

2026-11-18 11:31 更新

费用

get /organization/costs

获取组织的费用明细。

查询参数

  • start_time: integer

查询时间范围的起始时间(Unix 秒),包含该时刻。

  • api_key_ids: optional array of string

仅返回指定 API 密钥的费用。

  • bucket_width: optional "1d" (default: "1d")

响应中每个时间桶的时长。目前仅支持 1d,默认值为 1d。

  • "1d"

  • end_time: optional integer

查询时间范围的结束时间(Unix 秒),不包含该时刻。

  • group_by: optional array of "project_id" or "user_id" or "line_item" or 2 more

按指定字段对费用分组。支持 project_id、user_id、line_item、api_key_id 和 api_source。能否将 user_id 与 project_id 一起用于分组,或与 project_ids 筛选条件一起使用,取决于组织和查询时间范围。不支持的组合会返回 HTTP 400。按 api_source 分组时,已归因的 Agents API 活动记为 agents_api,其他活动记为 unlabeled。未按来源分组时,api_source 为 null。

  • "project_id"

  • "user_id"

  • "line_item"

  • "api_key_id"

  • "api_source"

  • limit: optional integer (default: 7)

限制返回的时间桶数量。取值范围为 1 至 180,默认值为 7。

  • line_items: optional array of string

仅返回完全匹配指定计费项目名称的费用。每个值必须匹配完整的 line_item 值,例如 gpt-6-astra, input_tokens。

  • page: optional string

分页游标,对应上一页响应中的 next_page 字段。

  • project_ids: optional array of string

仅返回指定项目的费用。

返回值

  • data: array of object { end_time, object, results, start_time }

  • end_time: integer

  • object: "bucket"

  • "bucket"

  • results: array of OrganizationUsageCompletionsResult { input_tokens, num_model_requests, object, 22 more } or OrganizationUsageEmbeddingsResult { input_tokens, num_model_requests, object, 4 more } or OrganizationUsageModerationsResult { input_tokens, num_model_requests, object, 4 more } or 8 more

  • OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 22 more }

该时间桶内汇总的补全用量明细。

  • input_tokens: integer

输入词元总数,包括缓存命中和写入缓存的词元,涵盖文本、音频及图像。订阅 Scale Tier 的客户还会计入 Scale Tier 词元。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.completions.result"

  • "organization.usage.completions.result"

  • output_tokens: integer

文本、音频和图像输出的词元总数。

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • api_source: optional "agents_api" or "unlabeled" or null

按 api_source 分组时,agents_api 标识已归因的 Agents API 活动,unlabeled 包括所有未公布来源归因的记录,含历史记录和来源未知的记录。unlabeled 本身无法判定记录是否来自直接调用 API。未按来源分组时,此字段为 null。

  • "agents_api"

  • "unlabeled"

  • batch: optional boolean or null

当 group_by=batch 时,此字段表示该分组是否属于批处理用量。

  • input_audio_tokens: optional integer

未命中缓存的音频输入词元总数。

  • input_cache_write_12h_tokens: optional integer

写入缓存并保留 12 小时的输入词元总数。

  • input_cache_write_30m_tokens: optional integer or null

写入缓存并保留 30 分钟的输入词元总数。较早的响应可能缺少此字段,或返回 null。

  • input_cache_write_tokens: optional integer

写入缓存的输入词元总数,合计 30 分钟和 12 小时两个保留期。

  • input_cached_audio_tokens: optional integer

命中缓存的音频输入词元总数。

  • input_cached_image_tokens: optional integer

命中缓存的图像输入词元总数。

  • input_cached_text_tokens: optional integer

命中缓存的文本输入词元总数。

  • input_cached_tokens: optional integer

命中缓存的文本、音频和图像输入词元总数。订阅 Scale Tier 的客户还会计入 Scale Tier 词元。

  • input_image_tokens: optional integer

未命中缓存的图像输入词元总数。

  • input_text_tokens: optional integer

未命中缓存的文本输入词元总数,扣除写入缓存的词元。

  • input_uncached_tokens: optional integer

未命中缓存的文本、音频和图像输入词元总数,扣除写入缓存的词元。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • output_audio_tokens: optional integer

音频输出词元总数。

  • output_image_tokens: optional integer

图像输出词元总数。

  • output_text_tokens: optional integer

文本输出词元总数。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • service_tier: optional string or null

当 group_by=service_tier 时,此字段给出该分组的服务层级。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }

该时间桶内汇总的嵌入用量明细。

  • input_tokens: integer

输入词元总数。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.embeddings.result"

  • "organization.usage.embeddings.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }

该时间桶内汇总的内容审核用量明细。

  • input_tokens: integer

输入词元总数。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.moderations.result"

  • "organization.usage.moderations.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }

该时间桶内汇总的图像用量明细。

  • images: integer

处理的图像数量。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.images.result"

  • "organization.usage.images.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • size: optional string or null

当 group_by=size 时,此字段给出该分组的图像尺寸。

  • source: optional string or null

当 group_by=source 时,此字段给出该分组的来源,取值包括 image.generation、image.edit 和 image.variation。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }

该时间桶内汇总的语音合成用量明细。

  • characters: integer

处理的字符数。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.audio_speeches.result"

  • "organization.usage.audio_speeches.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }

该时间桶内汇总的音频转录用量明细。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.audio_transcriptions.result"

  • "organization.usage.audio_transcriptions.result"

  • seconds: integer

处理的秒数。

format: int64

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }

该时间桶内汇总的向量存储用量明细。

  • object: "organization.usage.vector_stores.result"

  • "organization.usage.vector_stores.result"

  • usage_bytes: integer

向量存储用量,单位为字节。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }

该时间桶内汇总的代码解释器会话用量明细。

  • num_sessions: integer

代码解释器会话数量。

  • object: "organization.usage.code_interpreter_sessions.result"

  • "organization.usage.code_interpreter_sessions.result"

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }

该时间桶内汇总的文件搜索调用用量明细。

  • num_requests: integer

文件搜索调用次数。

  • object: "organization.usage.file_searches.result"

  • "organization.usage.file_searches.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • vector_store_id: optional string or null

当 group_by=vector_store_id 时,此字段给出该分组的向量存储 ID。

  • OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 6 more }

该时间桶内汇总的网页搜索调用用量明细。

  • num_model_requests: integer

模型请求次数。

  • num_requests: integer

网页搜索调用次数。

  • object: "organization.usage.web_searches.result"

  • "organization.usage.web_searches.result"

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • api_source: optional "agents_api" or "unlabeled" or null

按 api_source 分组时,agents_api 标识已归因的 Agents API 活动,unlabeled 包括所有未公布来源归因的记录,含历史记录和来源未知的记录。unlabeled 本身无法判定记录是否来自直接调用 API。未按来源分组时,此字段为 null。

  • "agents_api"

  • "unlabeled"

  • context_level: optional string or null

当 group_by=context_level 时,此字段给出该分组的搜索上下文大小。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • OrganizationCostsResult object { object, amount, api_key_id, 6 more }

该时间桶内汇总的费用明细。

  • object: "organization.costs.result"

  • "organization.costs.result"

  • amount: optional object { currency, value }

以对应币种计价的金额。

  • currency: optional string

小写的 ISO 4217 货币代码,例如 usd。

  • value: optional number

费用的数值。

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该费用分组的 API 密钥 ID。

  • api_source: optional "agents_api" or "unlabeled" or null

按 api_source 分组时,agents_api 标识已归因的 Agents API 活动,unlabeled 包括所有未公布来源归因的记录,含历史记录和来源未知的记录。unlabeled 本身无法判定记录是否来自直接调用 API。未按来源分组时,此字段为 null。

  • "agents_api"

  • "unlabeled"

  • line_item: optional string or null

当 group_by=line_item 时,此字段给出该费用分组的计费项目。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该费用分组的项目 ID。

  • quantity: optional number or null

当 group_by=line_item 时,此字段给出该费用分组的计量数量。

  • quantity_unit: optional CostQuantityUnit or null

quantity 的计量单位。如果该结果无法用单一受支持的单位表示,此字段为 null。

  • string

  • "tokens" or "1000_tokens" or "duration_seconds" or 5 more

quantity 的计量单位。如果该结果无法用单一受支持的单位表示,此字段为 null。

  • "tokens"

  • "1000_tokens"

  • "duration_seconds"

  • "duration_minutes"

  • "duration_hours"

  • "gibibyte_hours"

  • "images"

  • "characters"

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该费用分组的用户 ID。

  • start_time: integer

  • has_more: boolean

  • next_page: string or null

  • object: "page"

  • "page"

示例

## 从环境变量读取管理员密钥并查询组织费用
curl "https://api.openai.com/v1/organization/costs?start_time=0" \
    -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

200 — 通用响应示例

官方通用示例使用补全用量对象。当前接口的具体返回示例见本页下一组示例。

{
  "data": [
    {
      "end_time": 0,
      "object": "bucket",
      "results": [
        {
          "input_tokens": 0,
          "num_model_requests": 0,
          "object": "organization.usage.completions.result",
          "output_tokens": 0,
          "api_key_id": "api_key_id",
          "api_source": "agents_api",
          "batch": true,
          "input_audio_tokens": 0,
          "input_cache_write_12h_tokens": 0,
          "input_cache_write_30m_tokens": 0,
          "input_cache_write_tokens": 0,
          "input_cached_audio_tokens": 0,
          "input_cached_image_tokens": 0,
          "input_cached_text_tokens": 0,
          "input_cached_tokens": 0,
          "input_image_tokens": 0,
          "input_text_tokens": 0,
          "input_uncached_tokens": 0,
          "model": "model",
          "output_audio_tokens": 0,
          "output_image_tokens": 0,
          "output_text_tokens": 0,
          "project_id": "project_id",
          "service_tier": "service_tier",
          "user_id": "user_id"
        }
      ],
      "start_time": 0
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "page"
}

示例

## 从环境变量读取管理员密钥并查询组织费用
curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"

响应示例

{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1730419200,
            "end_time": 1730505600,
            "results": [
                {
                    "object": "organization.costs.result",
                    "amount": {
                        "value": 0.06,
                        "currency": "usd"
                    },
                    "line_item": null,
                    "project_id": null,
                    "api_key_id": null,
                    "quantity": null,
                    "quantity_unit": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号