feat(api): add reusable prompt IDs

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-3ae9c18dd7ccfc3ac5206f24394665f563a19015cfa8847b2801a2694d012abc.yml
-openapi_spec_hash: 48175b03b58805cd5c80793c66fd54e5
-config_hash: 4caff63b74a41f71006987db702f2918
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-9e41d2d5471d2c28bff0d616f4476f5b0e6c541ef4cb51bdaaef5fdf5e13c8b2.yml
+openapi_spec_hash: 86f765e18d00e32cf2ce9db7ab84d946
+config_hash: fd2af1d5eff0995bb7dc02ac9a34851d

api.md

@@ -677,6 +677,7 @@ Types:
 - <code><a href="./src/resources/responses/responses.ts">ResponseOutputRefusal</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseOutputText</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseOutputTextAnnotationAddedEvent</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponsePrompt</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseQueuedEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseReasoningDeltaEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseReasoningDoneEvent</a></code>

src/resources/chat/completions/completions.ts

@@ -291,7 +291,7 @@ export interface ChatCompletion {
    * When this parameter is set, the response body will include the `service_tier`
    * utilized.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
 
   /**
    * This fingerprint represents the backend configuration that the model runs with.
@@ -542,7 +542,7 @@ export interface ChatCompletionChunk {
    * When this parameter is set, the response body will include the `service_tier`
    * utilized.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
 
   /**
    * This fingerprint represents the backend configuration that the model runs with.
@@ -1464,7 +1464,7 @@ export interface ChatCompletionCreateParamsBase {
    * When this parameter is set, the response body will include the `service_tier`
    * utilized.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
 
   /**
    * Not supported with latest reasoning models `o3` and `o4-mini`.

src/resources/fine-tuning/jobs/jobs.ts

@@ -25,7 +25,7 @@ export class Jobs extends APIResource {
    * Response includes details of the enqueued job including job status and the name
    * of the fine-tuned models once complete.
    *
-   * [Learn more about fine-tuning](https://platform.openai.com/docs/guides/fine-tuning)
+   * [Learn more about fine-tuning](https://platform.openai.com/docs/guides/model-optimization)
    *
    * @example
    * ```ts
@@ -42,7 +42,7 @@ export class Jobs extends APIResource {
   /**
    * Get info about a fine-tuning job.
    *
-   * [Learn more about fine-tuning](https://platform.openai.com/docs/guides/fine-tuning)
+   * [Learn more about fine-tuning](https://platform.openai.com/docs/guides/model-optimization)
    *
    * @example
    * ```ts
@@ -449,7 +449,8 @@ export interface JobCreateParams {
    * [preference](https://platform.openai.com/docs/api-reference/fine-tuning/preference-input)
    * format.
    *
-   * See the [fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning)
+   * See the
+   * [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization)
    * for more details.
    */
   training_file: string;
@@ -508,7 +509,8 @@ export interface JobCreateParams {
    * Your dataset must be formatted as a JSONL file. You must upload your file with
    * the purpose `fine-tune`.
    *
-   * See the [fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning)
+   * See the
+   * [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization)
    * for more details.
    */
   validation_file?: string | null;

src/resources/images.ts

@@ -237,6 +237,20 @@ export interface ImageEditParams {
    */
   n?: number | null;
 
+  /**
+   * The compression level (0-100%) for the generated images. This parameter is only
+   * supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and
+   * defaults to 100.
+   */
+  output_compression?: number | null;
+
+  /**
+   * The format in which the generated images are returned. This parameter is only
+   * supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. The
+   * default value is `png`.
+   */
+  output_format?: 'png' | 'jpeg' | 'webp' | null;
+
   /**
    * The quality of the image that will be generated. `high`, `medium` and `low` are
    * only supported for `gpt-image-1`. `dall-e-2` only supports `standard` quality.

src/resources/responses/responses.ts

@@ -358,14 +358,13 @@ export interface Response {
   incomplete_details: Response.IncompleteDetails | null;
 
   /**
-   * Inserts a system (or developer) message as the first item in the model's
-   * context.
+   * A system (or developer) message inserted into the model's context.
    *
    * When using along with `previous_response_id`, the instructions from a previous
    * response will not be carried over to the next response. This makes it simple to
    * swap out system (or developer) messages in new responses.
    */
-  instructions: string | null;
+  instructions: string | Array<ResponseInputItem> | null;
 
   /**
    * Set of 16 key-value pairs that can be attached to an object. This can be useful
@@ -469,6 +468,12 @@ export interface Response {
    */
   previous_response_id?: string | null;
 
+  /**
+   * Reference to a prompt template and its variables.
+   * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
+   */
+  prompt?: ResponsePrompt | null;
+
   /**
    * **o-series models only**
    *
@@ -496,7 +501,7 @@ export interface Response {
    * When this parameter is set, the response body will include the `service_tier`
    * utilized.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
 
   /**
    * The status of the response generation. One of `completed`, `failed`,
@@ -3483,6 +3488,29 @@ export interface ResponseOutputTextAnnotationAddedEvent {
   type: 'response.output_text_annotation.added';
 }
 
+/**
+ * Reference to a prompt template and its variables.
+ * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
+ */
+export interface ResponsePrompt {
+  /**
+   * The unique identifier of the prompt template to use.
+   */
+  id: string;
+
+  /**
+   * Optional map of values to substitute in for variables in your prompt. The
+   * substitution values can either be strings, or other Response input types like
+   * images or files.
+   */
+  variables?: Record<string, string | ResponseInputText | ResponseInputImage | ResponseInputFile> | null;
+
+  /**
+   * Optional version of the prompt template.
+   */
+  version?: string | null;
+}
+
 /**
  * Emitted when a response is queued and waiting to be processed.
  */
@@ -4612,8 +4640,7 @@ export interface ResponseCreateParamsBase {
   include?: Array<ResponseIncludable> | null;
 
   /**
-   * Inserts a system (or developer) message as the first item in the model's
-   * context.
+   * A system (or developer) message inserted into the model's context.
    *
    * When using along with `previous_response_id`, the instructions from a previous
    * response will not be carried over to the next response. This makes it simple to
@@ -4650,6 +4677,12 @@ export interface ResponseCreateParamsBase {
    */
   previous_response_id?: string | null;
 
+  /**
+   * Reference to a prompt template and its variables.
+   * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
+   */
+  prompt?: ResponsePrompt | null;
+
   /**
    * **o-series models only**
    *
@@ -4677,7 +4710,7 @@ export interface ResponseCreateParamsBase {
    * When this parameter is set, the response body will include the `service_tier`
    * utilized.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
 
   /**
    * Whether to store the generated model response for later retrieval via API.
@@ -4922,6 +4955,7 @@ export declare namespace Responses {
     type ResponseOutputRefusal as ResponseOutputRefusal,
     type ResponseOutputText as ResponseOutputText,
     type ResponseOutputTextAnnotationAddedEvent as ResponseOutputTextAnnotationAddedEvent,
+    type ResponsePrompt as ResponsePrompt,
     type ResponseQueuedEvent as ResponseQueuedEvent,
     type ResponseReasoningDeltaEvent as ResponseReasoningDeltaEvent,
     type ResponseReasoningDoneEvent as ResponseReasoningDoneEvent,

tests/api-resources/images.test.ts

@@ -54,6 +54,8 @@ describe('resource images', () => {
       mask: await toFile(Buffer.from('# my file contents'), 'README.md'),
       model: 'string',
       n: 1,
+      output_compression: 100,
+      output_format: 'png',
       quality: 'high',
       response_format: 'url',
       size: '1024x1024',

tests/api-resources/responses/responses.test.ts

@@ -30,6 +30,7 @@ describe('resource responses', () => {
       metadata: { foo: 'string' },
       parallel_tool_calls: true,
       previous_response_id: 'previous_response_id',
+      prompt: { id: 'id', variables: { foo: 'string' }, version: 'version' },
       reasoning: { effort: 'low', generate_summary: 'auto', summary: 'auto' },
       service_tier: 'auto',
       store: true,