openai 7.26.0 → 7.28.0

package/src/lib/beta/agents/files.ts

@@ -0,0 +1,119 @@
+import type { OpenAI } from '../../../client';
+import { OpenAIError } from '../../../core/error';
+import { buildHeaders } from '../../../internal/headers';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Uploadable } from '../../../internal/uploads';
+import type { FileObject } from '../../../resources/files';
+import type {
+  EnvironmentFile,
+  FileCreateParams,
+  Files,
+} from '../../../resources/beta/agents/environments/files';
+
+/** Beta: file references ready for a hosted environment, plus caller-owned uploads. */
+export interface PreparedAgentFiles {
+  files: Extract<FileCreateParams, { type: 'file_id' }>[];
+  uploadedFiles: FileObject[];
+}
+
+/** Beta: uploaded file IDs remain available after partial preparation or staging failure. */
+export class AgentFileUploadError extends OpenAIError {
+  override readonly name = 'AgentFileUploadError';
+  declare readonly cause: unknown;
+  readonly uploadedFiles: FileObject[];
+  constructor(uploadedFiles: FileObject[], cause: unknown) {
+    super('Agent file preparation or staging failed; uploaded files remain caller-owned.');
+    this.uploadedFiles = uploadedFiles;
+    Object.defineProperty(this, 'cause', { value: cause, configurable: true });
+  }
+}
+
+/** @internal */
+export function validateAgentFilePath(path: string): void {
+  const parts = path.split('/');
+  const root = parts[2] ?? '';
+  if (
+    !path.startsWith('/workspace/') ||
+    path.includes('\\') ||
+    path.includes('\0') ||
+    parts.slice(1).some((part) => part === '' || part === '.' || part === '..') ||
+    root === '.codex' ||
+    root === '.managed-agents' ||
+    root.startsWith('.managed-agents-') ||
+    path === '/workspace/outputs'
+  ) {
+    throw new OpenAIError('Agent files require a non-reserved absolute file path inside /workspace');
+  }
+}
+
+function preflight(files: Record<string, Uploadable>, options: RequestOptions): [string, Uploadable][] {
+  const entries = Object.entries(files);
+  const headers = buildHeaders([options.headers]);
+  if (
+    entries.length > 1 &&
+    (headers.values.has('idempotency-key') ||
+      (!headers.nulls.has('idempotency-key') && options?.idempotencyKey !== undefined))
+  ) {
+    throw new OpenAIError('Do not reuse an Idempotency-Key across multiple file uploads');
+  }
+  const paths = new Set(entries.map(([path]) => path));
+  for (const [path] of entries) {
+    validateAgentFilePath(path);
+    for (let slash = path.lastIndexOf('/'); slash > 0; slash = path.lastIndexOf('/', slash - 1)) {
+      if (paths.has(path.slice(0, slash))) {
+        throw new OpenAIError('Agent file destinations conflict');
+      }
+    }
+  }
+  return entries;
+}
+
+/** @internal */
+export async function prepareAgentFiles(
+  client: OpenAI,
+  files: Record<string, Uploadable>,
+  options?: RequestOptions,
+): Promise<PreparedAgentFiles> {
+  const requestOptions = { ...options };
+  // Internal SDK read: capture effective headers once, including defaults and explicit omissions.
+  const headers = buildHeaders([client['_options'].defaultHeaders, requestOptions.headers]);
+  requestOptions.headers = headers;
+  const entries = preflight(files, requestOptions);
+  if (entries.length > 1) {
+    // Keep a later mutation of client defaults from adding one key to this entire batch.
+    headers.nulls.add('idempotency-key');
+  }
+  const prepared: PreparedAgentFiles = { files: [], uploadedFiles: [] };
+  try {
+    for (const [path, file] of entries) {
+      // oxlint-disable-next-line no-await-in-loop -- Stop on the first failure and expose precisely the uploads already created.
+      const uploaded = await client.files.create({ file, purpose: 'user_data' }, requestOptions);
+      prepared.uploadedFiles.push(uploaded);
+      prepared.files.push({ type: 'file_id', file_id: uploaded.id, path });
+    }
+    return prepared;
+  } catch (error) {
+    throw new AgentFileUploadError(prepared.uploadedFiles, error);
+  }
+}
+
+/** @internal */
+export async function uploadAgentFile(
+  client: OpenAI,
+  resource: Files,
+  environmentID: string,
+  params: { file: Uploadable; path: string },
+  options?: RequestOptions,
+): Promise<{ uploadedFile: FileObject; environmentFile: EnvironmentFile }> {
+  const prepared = await prepareAgentFiles(client, { [params.path]: params.file }, options);
+  const [reference] = prepared.files;
+  const [uploadedFile] = prepared.uploadedFiles;
+  if (!reference || !uploadedFile) {
+    throw new OpenAIError('Missing prepared agent file');
+  }
+  try {
+    return { uploadedFile, environmentFile: await resource.create(environmentID, reference, options) };
+  } catch (error) {
+    throw new AgentFileUploadError(prepared.uploadedFiles, error);
+  }
+}

package/src/lib/beta/agents/pages.ts

@@ -0,0 +1,32 @@
+import { OpenAIError } from '../../../core/error';
+import type { CursorPage } from '../../../core/pagination';
+import { isObj } from '../../../internal/utils/values';
+
+/** Retain server cursor metadata for legacy Agents items with nullable IDs.
+ * @internal
+ * @yields {T} Each item in server order, failing if pagination cannot advance.
+ */
+export async function* agentItems<T extends { id?: string | null }>(
+  load: (after: string | undefined) => PromiseLike<CursorPage<T>>,
+): AsyncGenerator<T, void, undefined> {
+  let after: string | undefined;
+  while (true) {
+    // oxlint-disable-next-line no-await-in-loop -- Each page determines the next cursor.
+    const page = await load(after);
+    yield* page.data;
+    if (!page.has_more) {
+      return;
+    }
+    // Internal SDK read: CursorPage keeps raw metadata but does not expose last_id.
+    // oxlint-disable-next-line prefer-destructuring -- Bracket access intentionally reads a protected internal field.
+    const body = page['body'];
+    // oxlint-disable-next-line unicorn/prefer-at -- Keep published source compatible with ES2020 declarations.
+    const last = page.data[page.data.length - 1];
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate only the opaque cursor from response metadata.
+    const cursor = isObj(body) && typeof body['last_id'] === 'string' ? body['last_id'] : last?.id;
+    if (!cursor || cursor === after) {
+      throw new OpenAIError('Agent pagination cannot advance to the next page');
+    }
+    after = cursor;
+  }
+}

package/src/lib/beta/agents/result-artifacts.ts

@@ -0,0 +1,76 @@
+import type { WritableStream } from '../../../internal/shim-types';
+import { agentItems } from './pages';
+import { OpenAIError } from '../../../core/error';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Artifacts, SessionArtifact } from '../../../resources/beta/agents/sessions/artifacts';
+import type { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: artifacts from the exact session and turn represented by a result. */
+export class AgentResultArtifacts {
+  readonly #resource: Artifacts;
+  readonly #sessionID: string;
+  readonly #turnID: string;
+  constructor(resource: Artifacts, result: AgentTurnResult) {
+    this.#resource = resource;
+    this.#sessionID = result.session_id;
+    this.#turnID = result.turn_id;
+  }
+
+  /** Find one immutable artifact by its exact hosted path, across all pages. */
+  async retrieve(path: string, options?: RequestOptions): Promise<SessionArtifact> {
+    let selected: SessionArtifact | undefined;
+    for await (const artifact of agentItems((after) =>
+      this.#resource.list(
+        this.#sessionID,
+        {},
+        { ...options, query: { ...options?.query, after, environment_id: undefined } },
+      ),
+    )) {
+      if (
+        artifact.session_id === this.#sessionID &&
+        artifact.turn_id === this.#turnID &&
+        artifact.path === path
+      ) {
+        if (selected) {
+          throw new OpenAIError('Multiple artifacts match this result and path');
+        }
+        selected = artifact;
+      }
+    }
+    if (!selected) {
+      throw new OpenAIError('No artifact matches this result and path');
+    }
+    return selected;
+  }
+
+  /** Return the native binary response for this result's exact artifact path. */
+  async content(path: string, options?: RequestOptions): Promise<Response> {
+    const artifact = await this.retrieve(path, options);
+    return this.#resource.content(artifact.id, { session_id: this.#sessionID }, options);
+  }
+
+  /** Stream bytes to a caller-chosen destination; the hosted path never selects a local path. */
+  async download(
+    params: { path: string; to: WritableStream<Uint8Array> },
+    options?: RequestOptions,
+  ): Promise<SessionArtifact> {
+    const { path, to } = params;
+    const artifact = await this.retrieve(path, options);
+    const response = await this.#resource.content(artifact.id, { session_id: this.#sessionID }, options);
+    if (!response.body) {
+      throw new OpenAIError('Artifact response has no content stream');
+    }
+    try {
+      await response.body.pipeTo(to, options?.signal ? { signal: options.signal } : {});
+    } catch (error) {
+      // pipeTo can reject before acquiring a reader, for example when the destination is locked.
+      try {
+        await response.body.cancel();
+      } catch {
+        /* already cancelled or owned by pipeTo */
+      }
+      throw error;
+    }
+    return artifact;
+  }
+}

package/src/resources/admin/organization/usage.ts

@@ -366,7 +366,14 @@ export namespace UsageAudioSpeechesResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -923,7 +930,14 @@ export namespace UsageAudioTranscriptionsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -1480,7 +1494,14 @@ export namespace UsageCodeInterpreterSessionsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -2037,7 +2058,14 @@ export namespace UsageCompletionsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -2594,7 +2622,14 @@ export namespace UsageCostsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -3151,7 +3186,14 @@ export namespace UsageEmbeddingsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -3708,7 +3750,14 @@ export namespace UsageFileSearchCallsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -4265,7 +4314,14 @@ export namespace UsageImagesResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -4822,7 +4878,14 @@ export namespace UsageModerationsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -5379,7 +5442,14 @@ export namespace UsageVectorStoresResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 
@@ -5936,7 +6006,14 @@ export namespace UsageWebSearchCallsResponse {
       input_audio_tokens?: number;
 
       /**
-       * The aggregated number of input tokens written to the cache.
+       * The aggregated number of input tokens written to the cache with a 12-hour
+       * retention period.
+       */
+      input_cache_write_12h_tokens?: number;
+
+      /**
+       * The aggregated number of input tokens written to the cache with a 30-minute
+       * retention period.
        */
       input_cache_write_tokens?: number;
 

package/src/resources/audio/audio.ts

@@ -31,11 +31,14 @@ import {
   TranslationVerbose,
   Translations,
 } from './translations';
+import * as VoicesAPI from './voices';
+import { Voice, VoiceCreateParams, Voices } from './voices';
 
 export class Audio extends APIResource {
   transcriptions: TranscriptionsAPI.Transcriptions = new TranscriptionsAPI.Transcriptions(this._client);
   translations: TranslationsAPI.Translations = new TranslationsAPI.Translations(this._client);
   speech: SpeechAPI.Speech = new SpeechAPI.Speech(this._client);
+  voices: VoicesAPI.Voices = new VoicesAPI.Voices(this._client);
 }
 
 export type AudioModel =
@@ -58,6 +61,7 @@ export type AudioResponseFormat = 'json' | 'text' | 'srt' | 'verbose_json' | 'vt
 Audio.Transcriptions = Transcriptions;
 Audio.Translations = Translations;
 Audio.Speech = Speech;
+Audio.Voices = Voices;
 
 export declare namespace Audio {
   export { type AudioModel as AudioModel, type AudioResponseFormat as AudioResponseFormat };
@@ -91,4 +95,6 @@ export declare namespace Audio {
   };
 
   export { Speech as Speech, type SpeechModel as SpeechModel, type SpeechCreateParams as SpeechCreateParams };
+
+  export { Voices as Voices, type Voice as Voice, type VoiceCreateParams as VoiceCreateParams };
 }

package/src/resources/audio/index.ts

@@ -28,3 +28,4 @@ export {
   type TranslationCreateResponse,
   type TranslationCreateParams,
 } from './translations';
+export { Voices, type Voice, type VoiceCreateParams } from './voices';

package/src/resources/audio/speech.ts

@@ -69,6 +69,8 @@ export interface SpeechCreateParams {
    * object with an `id`, for example `{ "id": "voice_1234" }`. Previews of the
    * voices are available in the
    * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
+   * Custom voices must be created from audio samples. Voices created from text
+   * prompts are supported only in Live.
    */
   voice:
     | string

package/src/resources/audio/voices.ts

@@ -0,0 +1,152 @@
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+
+function resolveResourceRequestOptions(
+  options: RequestOptions | undefined,
+  buildOptions: (options: RequestOptions | undefined) => RequestOptions | Promise<RequestOptions>,
+): Promise<RequestOptions> {
+  return Promise.resolve(options).then(buildOptions);
+}
+
+/**
+ * Turn audio into text or text into audio.
+ */
+export class Voices extends APIResource {
+  /**
+   * Creates a voice from a text prompt or from a consent recording and an audio
+   * sample.
+   *
+   * For prompt-based creation, send `type: "prompt"` with a `name` and `prompt` as
+   * JSON or multipart form data. For creation from an audio sample, send
+   * `type: "audio_sample"` with a `name`, `audio_sample`, and `consent` recording ID
+   * as multipart form data. The type defaults to `audio_sample` when omitted.
+   *
+   * Returns the saved voice's metadata. Voices created from text prompts are
+   * supported only in Live, not in Realtime or the speech endpoint. The response
+   * does not include preview audio.
+   *
+   * @example
+   * ```ts
+   * const voice = await client.audio.voices.create({
+   *   audio_sample: fs.createReadStream('path/to/file'),
+   *   consent: 'consent',
+   *   name: 'x',
+   * });
+   * ```
+   */
+  create(body: VoiceCreateParams, options?: RequestOptions): APIPromise<Voice> {
+    return this._client.post(
+      '/audio/voices',
+      resolveResourceRequestOptions(options, (options) =>
+        multipartFormRequestOptions({ body, ...options, __security: { bearerAuth: true } }, this._client),
+      ),
+    );
+  }
+}
+
+/**
+ * A custom voice that can be used for audio output. Voices created from text
+ * prompts are supported only in Live.
+ */
+export interface Voice {
+  /**
+   * The voice identifier, which can be referenced in API endpoints.
+   */
+  id: string;
+
+  /**
+   * The Unix timestamp (in seconds) for when the voice was created.
+   */
+  created_at: number;
+
+  /**
+   * The name of the voice.
+   */
+  name: string;
+
+  /**
+   * The object type, which is always `audio.voice`.
+   */
+  object: 'audio.voice';
+
+  /**
+   * How the voice was created. Voices created from text prompts are supported only
+   * in Live.
+   */
+  type: 'audio_sample' | 'prompt';
+}
+
+export type VoiceCreateParams = VoiceCreateParams.Consent | VoiceCreateParams.Prompt;
+
+export declare namespace VoiceCreateParams {
+  /**
+   * Creates a voice from a consent recording and an audio sample. Requires
+   * multipart/form-data.
+   */
+  export interface Consent {
+    /**
+     * The sample audio recording file. Maximum size is 10 MiB.
+     *
+     * Supported MIME types: `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/ogg`,
+     * `audio/aac`, `audio/flac`, `audio/webm`, `audio/mp4`.
+     */
+    audio_sample: Uploadable;
+
+    /**
+     * The consent recording ID (for example, `cons_1234`).
+     */
+    consent: string;
+
+    /**
+     * The name of the new voice.
+     */
+    name: string;
+
+    /**
+     * The voice creation method. Defaults to `audio_sample` when omitted.
+     */
+    type?: 'audio_sample';
+  }
+
+  /**
+   * Creates a synthetic voice from a text description. Supports application/json or
+   * multipart/form-data.
+   */
+  export interface Prompt {
+    /**
+     * The name of the new voice.
+     */
+    name: string;
+
+    /**
+     * A description of the desired voice. Must not contain only whitespace.
+     */
+    prompt: string;
+
+    /**
+     * Set to `prompt` to create a voice from a text description.
+     */
+    type: 'prompt';
+
+    /**
+     * The voice creation model to use. Defaults to `auto`.
+     */
+    model?: string | 'auto' | '2026-10-01';
+
+    /**
+     * Optional text for the voice to speak during creation. If omitted, a script is
+     * generated from the prompt. Must not be blank after trimming whitespace; scripts
+     * that are too short are rejected.
+     */
+    script_hint?: string;
+  }
+}
+
+export declare namespace Voices {
+  export { type Voice as Voice, type VoiceCreateParams as VoiceCreateParams };
+}

package/src/resources/beta/agents/agents.ts

@@ -5372,9 +5372,8 @@ export interface AgentCreateParams {
    * - `flex` - Uses the flex service tier.
    * - `priority` - Uses the priority service tier.
    * - `fast` - Uses the fast service tier.
-   * - `ultrafast` - Uses the ultrafast service tier.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | null;
 
   /**
    * Configuration for generated text. Defaults to the `text` format and medium
@@ -5431,9 +5430,8 @@ export interface AgentUpdateParams {
    * - `flex` - Uses the flex service tier.
    * - `priority` - Uses the priority service tier.
    * - `fast` - Uses the fast service tier.
-   * - `ultrafast` - Uses the ultrafast service tier.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | null;
 
   /**
    * Configuration for text generated by the agent.

package/src/resources/beta/agents/environments/files.ts

@@ -1,5 +1,11 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
+import {
+  prepareAgentFiles,
+  uploadAgentFile,
+  type PreparedAgentFiles,
+} from '../../../../lib/beta/agents/files';
+import type { Uploadable } from '../../../../internal/uploads';
 import { APIResource } from '../../../../core/resource';
 import { APIPromise } from '../../../../core/api-promise';
 import { PagePromise, TokenPage, type TokenPageParams } from '../../../../core/pagination';
@@ -15,6 +21,16 @@ function resolveResourceRequestOptions(
 }
 
 export class Files extends APIResource {
+  /** Beta: prepare initial hosted file references; uploaded Files API objects remain caller-owned. */
+  prepare(files: Record<string, Uploadable>, options?: RequestOptions): Promise<PreparedAgentFiles> {
+    return prepareAgentFiles(this._client, files, options);
+  }
+
+  /** Beta: upload one local file and stage its reference in a live environment. */
+  upload(environmentID: string, params: { file: Uploadable; path: string }, options?: RequestOptions) {
+    return uploadAgentFile(this._client, this, environmentID, params, options);
+  }
+
   /**
    * Copies inline bytes or a Files API file into a connected execution environment.
    * See

package/src/resources/beta/agents/sessions/artifacts.ts

@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
+import { AgentResultArtifacts } from '../../../../lib/beta/agents/result-artifacts';
+import type { AgentTurnResult } from '../../../../lib/beta/agents/agent-turn-result';
 import { APIResource } from '../../../../core/resource';
 import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
@@ -122,6 +124,11 @@ function normalizeRequestOptionsForQuery(
 }
 
 export class Artifacts extends APIResource {
+  /** Beta: bind artifact lookup and downloads to a completed result's exact session and turn. */
+  forResult(result: AgentTurnResult): AgentResultArtifacts {
+    return new AgentResultArtifacts(this, result);
+  }
+
   /**
    * Retrieves immutable metadata for one durable session artifact. See
    * [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).