feat(api): update usage APIs and documentation

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: fef4a7f1-bbb1-45f0-99ff-ccc9f962820c
-openapi_spec_hash: 4af7018ff56446e0398fc7946a92680f
-openapi_transformed_spec_hash: b2689771e08c3fdc6ae8f0433dc2c784
-config_hash: 5c00fe18ea913ed0186f9894adc02a70
-codegen_sha: d7faac0f7cd09f79c36bdbf92b14bfdf7788c5d6
-codegen_hash: f7073339e9e47087c5bd68e1fcea6e89f6b985354331b8c2fd53580c4bc9300b
-public_codegen_sha: 8018025c5e6a1e4d0e4f0ddd21b550dd7191b799
+generation_id: a2e15f59-94b2-41a7-83a2-0aa28ffd7091
+openapi_spec_hash: 0ba3e4acd88b521d832e2a42d5471e00
+openapi_transformed_spec_hash: 0a6002520553b981f4c0bf6555a0a623
+config_hash: d8813efd847d1966dd7f03bb648c41dc
+codegen_sha: 23fe5abcd01bf9d6dd1c1ee49b6244f9d2d078ce
+codegen_hash: 2c513214ca2f30afc9ae2724d5b78c068dac45d959bc1c4f1d8b4706f507f3ca
+public_codegen_sha: 0c208e28bddcefe8be7b5a0b94be94b8b973ed4e

openai-java-core/src/main/kotlin/com/openai/models/Reasoning.kt

@@ -18,8 +18,6 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * **gpt-5 and o-series models only**
- *
  * Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
  */
 class Reasoning

openai-java-core/src/main/kotlin/com/openai/models/admin/organization/usage/UsageCostsParams.kt

@@ -24,6 +24,7 @@ private constructor(
     private val endTime: Long?,
     private val groupBy: List<GroupBy>?,
     private val limit: Long?,
+    private val lineItems: List<String>?,
     private val page: String?,
     private val projectIds: List<String>?,
     private val additionalHeaders: Headers,
@@ -54,6 +55,12 @@ private constructor(
      */
     fun limit(): Optional<Long> = Optional.ofNullable(limit)
 
+    /**
+     * Return only costs for these exact line item names. Each value must match the complete
+     * `line_item` value, for example `gpt-5.6-sol, input_tokens`.
+     */
+    fun lineItems(): Optional<List<String>> = Optional.ofNullable(lineItems)
+
     /**
      * A cursor for use in pagination. Corresponding to the `next_page` field from the previous
      * response.
@@ -93,6 +100,7 @@ private constructor(
         private var endTime: Long? = null
         private var groupBy: MutableList<GroupBy>? = null
         private var limit: Long? = null
+        private var lineItems: MutableList<String>? = null
         private var page: String? = null
         private var projectIds: MutableList<String>? = null
         private var additionalHeaders: Headers.Builder = Headers.builder()
@@ -106,6 +114,7 @@ private constructor(
             endTime = usageCostsParams.endTime
             groupBy = usageCostsParams.groupBy?.toMutableList()
             limit = usageCostsParams.limit
+            lineItems = usageCostsParams.lineItems?.toMutableList()
             page = usageCostsParams.page
             projectIds = usageCostsParams.projectIds?.toMutableList()
             additionalHeaders = usageCostsParams.additionalHeaders.toBuilder()
@@ -187,6 +196,26 @@ private constructor(
         /** Alias for calling [Builder.limit] with `limit.orElse(null)`. */
         fun limit(limit: Optional<Long>) = limit(limit.getOrNull())
 
+        /**
+         * Return only costs for these exact line item names. Each value must match the complete
+         * `line_item` value, for example `gpt-5.6-sol, input_tokens`.
+         */
+        fun lineItems(lineItems: List<String>?) = apply {
+            this.lineItems = lineItems?.toMutableList()
+        }
+
+        /** Alias for calling [Builder.lineItems] with `lineItems.orElse(null)`. */
+        fun lineItems(lineItems: Optional<List<String>>) = lineItems(lineItems.getOrNull())
+
+        /**
+         * Adds a single [String] to [lineItems].
+         *
+         * @throws IllegalStateException if the field was previously set to a non-list.
+         */
+        fun addLineItem(lineItem: String) = apply {
+            lineItems = (lineItems ?: mutableListOf()).apply { add(lineItem) }
+        }
+
         /**
          * A cursor for use in pagination. Corresponding to the `next_page` field from the previous
          * response.
@@ -331,6 +360,7 @@ private constructor(
                 endTime,
                 groupBy?.toImmutable(),
                 limit,
+                lineItems?.toImmutable(),
                 page,
                 projectIds?.toImmutable(),
                 additionalHeaders.build(),
@@ -349,6 +379,7 @@ private constructor(
                 endTime?.let { put("end_time", it.toString()) }
                 groupBy?.forEach { put("group_by[]", it.toString()) }
                 limit?.let { put("limit", it.toString()) }
+                lineItems?.forEach { put("line_items[]", it) }
                 page?.let { put("page", it) }
                 projectIds?.forEach { put("project_ids[]", it) }
                 putAll(additionalQueryParams)
@@ -639,6 +670,7 @@ private constructor(
             endTime == other.endTime &&
             groupBy == other.groupBy &&
             limit == other.limit &&
+            lineItems == other.lineItems &&
             page == other.page &&
             projectIds == other.projectIds &&
             additionalHeaders == other.additionalHeaders &&
@@ -653,12 +685,13 @@ private constructor(
             endTime,
             groupBy,
             limit,
+            lineItems,
             page,
             projectIds,
             additionalHeaders,
             additionalQueryParams,
         )
 
     override fun toString() =
-        "UsageCostsParams{startTime=$startTime, apiKeyIds=$apiKeyIds, bucketWidth=$bucketWidth, endTime=$endTime, groupBy=$groupBy, limit=$limit, page=$page, projectIds=$projectIds, additionalHeaders=$additionalHeaders, additionalQueryParams=$additionalQueryParams}"
+        "UsageCostsParams{startTime=$startTime, apiKeyIds=$apiKeyIds, bucketWidth=$bucketWidth, endTime=$endTime, groupBy=$groupBy, limit=$limit, lineItems=$lineItems, page=$page, projectIds=$projectIds, additionalHeaders=$additionalHeaders, additionalQueryParams=$additionalQueryParams}"
 }

openai-java-core/src/main/kotlin/com/openai/models/batches/Batch.kt

@@ -269,9 +269,9 @@ private constructor(
     fun metadata(): Optional<Metadata> = metadata.getOptional("metadata")
 
     /**
-     * Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI offers a wide range of
-     * models with different capabilities, performance characteristics, and price points. Refer to
-     * the [model guide](https://platform.openai.com/docs/models) to browse and compare available
+     * Model ID used to process the batch, like `gpt-5.6-sol`. OpenAI offers a wide range of models
+     * with different capabilities, performance characteristics, and price points. Refer to the
+     * [model guide](https://platform.openai.com/docs/models) to browse and compare available
      * models.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
@@ -774,9 +774,9 @@ private constructor(
         fun metadata(metadata: JsonField<Metadata>) = apply { this.metadata = metadata }
 
         /**
-         * Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI offers a wide range
-         * of models with different capabilities, performance characteristics, and price points.
-         * Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare
+         * Model ID used to process the batch, like `gpt-5.6-sol`. OpenAI offers a wide range of
+         * models with different capabilities, performance characteristics, and price points. Refer
+         * to the [model guide](https://platform.openai.com/docs/models) to browse and compare
          * available models.
          */
         fun model(model: String) = model(JsonField.of(model))

openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponse.kt

@@ -256,7 +256,7 @@ private constructor(
     fun metadata(): Optional<Metadata> = metadata.getOptional("metadata")
 
     /**
-     * Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of
+     * Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI offers a wide range of
      * models with different capabilities, performance characteristics, and price points. Refer to
      * the [model guide](https://platform.openai.com/docs/models) to browse and compare available
      * models.
@@ -473,8 +473,6 @@ private constructor(
         promptCacheRetention.getOptional("prompt_cache_retention")
 
     /**
-     * **gpt-5 and o-series models only**
-     *
      * Configuration options for
      * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
      *
@@ -1087,9 +1085,9 @@ private constructor(
         fun metadata(metadata: JsonField<Metadata>) = apply { this.metadata = metadata }
 
         /**
-         * Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range
-         * of models with different capabilities, performance characteristics, and price points.
-         * Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare
+         * Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI offers a wide range of
+         * models with different capabilities, performance characteristics, and price points. Refer
+         * to the [model guide](https://platform.openai.com/docs/models) to browse and compare
          * available models.
          */
         fun model(model: Model) = model(JsonField.of(model))
@@ -1925,8 +1923,6 @@ private constructor(
         }
 
         /**
-         * **gpt-5 and o-series models only**
-         *
          * Configuration options for
          * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
          */
@@ -2458,6 +2454,8 @@ private constructor(
 
                 @JvmField val MAX_OUTPUT_TOKENS = of("max_output_tokens")
 
+                @JvmField val MAX_MESSAGES = of("max_messages")
+
                 @JvmField val CONTENT_FILTER = of("content_filter")
 
                 @JvmStatic fun of(value: String) = Reason(JsonField.of(value))
@@ -2466,6 +2464,7 @@ private constructor(
             /** An enum containing [Reason]'s known values. */
             enum class Known {
                 MAX_OUTPUT_TOKENS,
+                MAX_MESSAGES,
                 CONTENT_FILTER,
             }
 
@@ -2480,6 +2479,7 @@ private constructor(
              */
             enum class Value {
                 MAX_OUTPUT_TOKENS,
+                MAX_MESSAGES,
                 CONTENT_FILTER,
                 /**
                  * An enum member indicating that [Reason] was instantiated with an unknown value.
@@ -2497,6 +2497,7 @@ private constructor(
             fun value(): Value =
                 when (this) {
                     MAX_OUTPUT_TOKENS -> Value.MAX_OUTPUT_TOKENS
+                    MAX_MESSAGES -> Value.MAX_MESSAGES
                     CONTENT_FILTER -> Value.CONTENT_FILTER
                     else -> Value._UNKNOWN
                 }
@@ -2513,6 +2514,7 @@ private constructor(
             fun known(): Known =
                 when (this) {
                     MAX_OUTPUT_TOKENS -> Known.MAX_OUTPUT_TOKENS
+                    MAX_MESSAGES -> Known.MAX_MESSAGES
                     CONTENT_FILTER -> Known.CONTENT_FILTER
                     else -> throw OpenAIInvalidDataException("Unknown Reason: $value")
                 }
@@ -2951,7 +2953,7 @@ private constructor(
     }
 
     /**
-     * Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of
+     * Model ID used to generate the response, like `gpt-5.6-sol`. OpenAI offers a wide range of
      * models with different capabilities, performance characteristics, and price points. Refer to
      * the [model guide](https://platform.openai.com/docs/models) to browse and compare available
      * models.
@@ -7893,8 +7895,6 @@ private constructor(
     }
 
     /**
-     * **gpt-5 and o-series models only**
-     *
      * Configuration options for
      * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
      */