v4.0.0-beta.11

Author: schnerd

api.md

@@ -4,6 +4,7 @@ Types:
 
 - <code><a href="./src/resources/completions.ts">Completion</a></code>
 - <code><a href="./src/resources/completions.ts">CompletionChoice</a></code>
+- <code><a href="./src/resources/completions.ts">CompletionUsage</a></code>
 
 Methods:
 
@@ -38,11 +39,12 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/embeddings.ts">CreateEmbeddingResponse</a></code>
 - <code><a href="./src/resources/embeddings.ts">Embedding</a></code>
 
 Methods:
 
-- <code title="post /embeddings">client.embeddings.<a href="./src/resources/embeddings.ts">create</a>({ ...params }) -> Embedding</code>
+- <code title="post /embeddings">client.embeddings.<a href="./src/resources/embeddings.ts">create</a>({ ...params }) -> CreateEmbeddingResponse</code>
 
 # Files
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openai",
-  "version": "4.0.0-beta.10",
+  "version": "4.0.0-beta.11",
   "description": "Client library for the OpenAI API",
   "author": "OpenAI <support@openai.com>",
   "types": "dist/index.d.ts",

src/index.ts

@@ -192,6 +192,7 @@ export namespace OpenAI {
   export import Completions = API.Completions;
   export import Completion = API.Completion;
   export import CompletionChoice = API.CompletionChoice;
+  export import CompletionUsage = API.CompletionUsage;
   export import CompletionCreateParams = API.CompletionCreateParams;
   export import CompletionCreateParamsNonStreaming = API.CompletionCreateParamsNonStreaming;
   export import CompletionCreateParamsStreaming = API.CompletionCreateParamsStreaming;
@@ -203,6 +204,7 @@ export namespace OpenAI {
   export import EditCreateParams = API.EditCreateParams;
 
   export import Embeddings = API.Embeddings;
+  export import CreateEmbeddingResponse = API.CreateEmbeddingResponse;
   export import Embedding = API.Embedding;
   export import EmbeddingCreateParams = API.EmbeddingCreateParams;
 

src/resources/audio/transcriptions.ts

@@ -21,7 +21,7 @@ export interface Transcription {
 export interface TranscriptionCreateParams {
   /**
    * The audio file object (not file name) to transcribe, in one of these formats:
-   * mp3, mp4, mpeg, mpga, m4a, wav, or webm.
+   * flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
    */
   file: Uploadable;
 

src/resources/audio/translations.ts

@@ -20,8 +20,8 @@ export interface Translation {
 
 export interface TranslationCreateParams {
   /**
-   * The audio file object (not file name) translate, in one of these formats: mp3,
-   * mp4, mpeg, mpga, m4a, wav, or webm.
+   * The audio file object (not file name) translate, in one of these formats: flac,
+   * mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
    */
   file: Uploadable;
 

src/resources/chat/completions.ts

@@ -3,6 +3,7 @@
 import * as Core from 'openai/core';
 import { APIPromise } from 'openai/core';
 import { APIResource } from 'openai/resource';
+import * as Completions_ from 'openai/resources/completions';
 import * as API from './index';
 import { Stream } from 'openai/streaming';
 
@@ -25,60 +26,122 @@ export class Completions extends APIResource {
   }
 }
 
+/**
+ * Represents a chat completion response returned by model, based on the provided
+ * input.
+ */
 export interface ChatCompletion {
+  /**
+   * A unique identifier for the chat completion.
+   */
   id: string;
 
+  /**
+   * A list of chat completion choices. Can be more than one if `n` is greater
+   * than 1.
+   */
   choices: Array<ChatCompletion.Choice>;
 
+  /**
+   * A unix timestamp of when the chat completion was created.
+   */
   created: number;
 
+  /**
+   * The model used for the chat completion.
+   */
   model: string;
 
+  /**
+   * The object type, which is always `chat.completion`.
+   */
   object: string;
 
-  usage?: ChatCompletion.Usage;
+  /**
+   * Usage statistics for the completion request.
+   */
+  usage?: Completions_.CompletionUsage;
 }
 
 export namespace ChatCompletion {
   export interface Choice {
+    /**
+     * The reason the model stopped generating tokens. This will be `stop` if the model
+     * hit a natural stop point or a provided stop sequence, `length` if the maximum
+     * number of tokens specified in the request was reached, or `function_call` if the
+     * model called a function.
+     */
     finish_reason: 'stop' | 'length' | 'function_call';
 
+    /**
+     * The index of the choice in the list of choices.
+     */
     index: number;
 
+    /**
+     * A chat completion message generated by the model.
+     */
     message: ChatCompletionMessage;
   }
-
-  export interface Usage {
-    completion_tokens: number;
-
-    prompt_tokens: number;
-
-    total_tokens: number;
-  }
 }
 
+/**
+ * Represents a streamed chunk of a chat completion response returned by model,
+ * based on the provided input.
+ */
 export interface ChatCompletionChunk {
+  /**
+   * A unique identifier for the chat completion chunk.
+   */
   id: string;
 
+  /**
+   * A list of chat completion choices. Can be more than one if `n` is greater
+   * than 1.
+   */
   choices: Array<ChatCompletionChunk.Choice>;
 
+  /**
+   * A unix timestamp of when the chat completion chunk was created.
+   */
   created: number;
 
+  /**
+   * The model to generate the completion.
+   */
   model: string;
 
+  /**
+   * The object type, which is always `chat.completion.chunk`.
+   */
   object: string;
 }
 
 export namespace ChatCompletionChunk {
   export interface Choice {
+    /**
+     * A chat completion delta generated by streamed model responses.
+     */
     delta: Choice.Delta;
 
+    /**
+     * The reason the model stopped generating tokens. This will be `stop` if the model
+     * hit a natural stop point or a provided stop sequence, `length` if the maximum
+     * number of tokens specified in the request was reached, or `function_call` if the
+     * model called a function.
+     */
     finish_reason: 'stop' | 'length' | 'function_call' | null;
 
+    /**
+     * The index of the choice in the list of choices.
+     */
     index: number;
   }
 
   export namespace Choice {
+    /**
+     * A chat completion delta generated by streamed model responses.
+     */
     export interface Delta {
       /**
        * The contents of the chunk message.
@@ -120,6 +183,9 @@ export namespace ChatCompletionChunk {
   }
 }
 
+/**
+ * A chat completion message generated by the model.
+ */
 export interface ChatCompletionMessage {
   /**
    * The contents of the message.

src/resources/completions.ts

@@ -25,31 +25,48 @@ export class Completions extends APIResource {
   }
 }
 
+/**
+ * Represents a completion response from the API. Note: both the streamed and
+ * non-streamed response objects share the same shape (unlike the chat endpoint).
+ */
 export interface Completion {
+  /**
+   * A unique identifier for the completion.
+   */
   id: string;
 
+  /**
+   * The list of completion choices the model generated for the input prompt.
+   */
   choices: Array<CompletionChoice>;
 
+  /**
+   * The Unix timestamp of when the completion was created.
+   */
   created: number;
 
+  /**
+   * The model used for completion.
+   */
   model: string;
 
+  /**
+   * The object type, which is always "text_completion"
+   */
   object: string;
 
-  usage?: Completion.Usage;
-}
-
-export namespace Completion {
-  export interface Usage {
-    completion_tokens: number;
-
-    prompt_tokens: number;
-
-    total_tokens: number;
-  }
+  /**
+   * Usage statistics for the completion request.
+   */
+  usage?: CompletionUsage;
 }
 
 export interface CompletionChoice {
+  /**
+   * The reason the model stopped generating tokens. This will be `stop` if the model
+   * hit a natural stop point or a provided stop sequence, or `length` if the maximum
+   * number of tokens specified in the request was reached.
+   */
   finish_reason: 'stop' | 'length';
 
   index: number;
@@ -71,6 +88,26 @@ export namespace CompletionChoice {
   }
 }
 
+/**
+ * Usage statistics for the completion request.
+ */
+export interface CompletionUsage {
+  /**
+   * Number of tokens in the generated completion.
+   */
+  completion_tokens: number;
+
+  /**
+   * Number of tokens in the prompt.
+   */
+  prompt_tokens: number;
+
+  /**
+   * Total number of tokens used in the request (prompt + completion).
+   */
+  total_tokens: number;
+}
+
 export interface CompletionCreateParams {
   /**
    * ID of the model to use. You can use the
@@ -258,6 +295,7 @@ export interface CompletionCreateParamsStreaming extends CompletionCreateParams
 export namespace Completions {
   export import Completion = API.Completion;
   export import CompletionChoice = API.CompletionChoice;
+  export import CompletionUsage = API.CompletionUsage;
   export import CompletionCreateParams = API.CompletionCreateParams;
   export import CompletionCreateParamsNonStreaming = API.CompletionCreateParamsNonStreaming;
   export import CompletionCreateParamsStreaming = API.CompletionCreateParamsStreaming;

src/resources/edits.ts

@@ -2,6 +2,7 @@
 
 import * as Core from 'openai/core';
 import { APIResource } from 'openai/resource';
+import * as Completions from 'openai/resources/completions';
 import * as API from './index';
 
 export class Edits extends APIResource {
@@ -18,31 +19,46 @@ export class Edits extends APIResource {
 }
 
 export interface Edit {
+  /**
+   * A list of edit choices. Can be more than one if `n` is greater than 1.
+   */
   choices: Array<Edit.Choice>;
 
+  /**
+   * A unix timestamp of when the edit was created.
+   */
   created: number;
 
+  /**
+   * The object type, which is always `edit`.
+   */
   object: string;
 
-  usage: Edit.Usage;
+  /**
+   * Usage statistics for the completion request.
+   */
+  usage: Completions.CompletionUsage;
 }
 
 export namespace Edit {
   export interface Choice {
+    /**
+     * The reason the model stopped generating tokens. This will be `stop` if the model
+     * hit a natural stop point or a provided stop sequence, or `length` if the maximum
+     * number of tokens specified in the request was reached.
+     */
     finish_reason: 'stop' | 'length';
 
+    /**
+     * The index of the choice in the list of choices.
+     */
     index: number;
 
+    /**
+     * The edited result.
+     */
     text: string;
   }
-
-  export interface Usage {
-    completion_tokens: number;
-
-    prompt_tokens: number;
-
-    total_tokens: number;
-  }
 }
 
 export interface EditCreateParams {

src/resources/embeddings.ts

@@ -8,37 +8,74 @@ export class Embeddings extends APIResource {
   /**
    * Creates an embedding vector representing the input text.
    */
-  create(body: EmbeddingCreateParams, options?: Core.RequestOptions): Core.APIPromise<Embedding> {
+  create(
+    body: EmbeddingCreateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<CreateEmbeddingResponse> {
     return this.post('/embeddings', { body, ...options });
   }
 }
 
-export interface Embedding {
-  data: Array<Embedding.Data>;
+export interface CreateEmbeddingResponse {
+  /**
+   * The list of embeddings generated by the model.
+   */
+  data: Array<Embedding>;
 
+  /**
+   * The name of the model used to generate the embedding.
+   */
   model: string;
 
+  /**
+   * The object type, which is always "embedding".
+   */
   object: string;
 
-  usage: Embedding.Usage;
+  /**
+   * The usage information for the request.
+   */
+  usage: CreateEmbeddingResponse.Usage;
 }
 
-export namespace Embedding {
-  export interface Data {
-    embedding: Array<number>;
-
-    index: number;
-
-    object: string;
-  }
-
+export namespace CreateEmbeddingResponse {
+  /**
+   * The usage information for the request.
+   */
   export interface Usage {
+    /**
+     * The number of tokens used by the prompt.
+     */
     prompt_tokens: number;
 
+    /**
+     * The total number of tokens used by the request.
+     */
     total_tokens: number;
   }
 }
 
+/**
+ * Represents an embedding vector returned by embedding endpoint.
+ */
+export interface Embedding {
+  /**
+   * The embedding vector, which is a list of floats. The length of vector depends on
+   * the model as listed in the [embedding guide](/docs/guides/embeddings).
+   */
+  embedding: Array<number>;
+
+  /**
+   * The index of the embedding in the list of embeddings.
+   */
+  index: number;
+
+  /**
+   * The object type, which is always "embedding".
+   */
+  object: string;
+}
+
 export interface EmbeddingCreateParams {
   /**
    * Input text to embed, encoded as a string or array of tokens. To embed multiple
@@ -66,6 +103,7 @@ export interface EmbeddingCreateParams {
 }
 
 export namespace Embeddings {
+  export import CreateEmbeddingResponse = API.CreateEmbeddingResponse;
   export import Embedding = API.Embedding;
   export import EmbeddingCreateParams = API.EmbeddingCreateParams;
 }

src/resources/files.ts

@@ -66,21 +66,50 @@ export interface FileDeleted {
   object: string;
 }
 
+/**
+ * The `File` object represents a document that has been uploaded to OpenAI.
+ */
 export interface FileObject {
+  /**
+   * The file identifier, which can be referenced in the API endpoints.
+   */
   id: string;
 
+  /**
+   * The size of the file in bytes.
+   */
   bytes: number;
 
+  /**
+   * The unix timestamp for when the file was created.
+   */
   created_at: number;
 
+  /**
+   * The name of the file.
+   */
   filename: string;
 
+  /**
+   * The object type, which is always "file".
+   */
   object: string;
 
+  /**
+   * The intended purpose of the file. Currently, only "fine-tune" is supported.
+   */
   purpose: string;
 
+  /**
+   * The current status of the file, which can be either `uploaded`, `processed`,
+   * `pending`, `error`, `deleting` or `deleted`.
+   */
   status?: string;
 
+  /**
+   * Additional details about the status of the file. If the file is in the `error`
+   * state, this will include a message describing the error.
+   */
   status_details?: string | null;
 }
 

src/resources/fine-tunes.ts

@@ -78,48 +78,121 @@ export class FineTunesPage extends Page<FineTune> {}
 // alias so we can export it in the namespace
 type _FineTunesPage = FineTunesPage;
 
+/**
+ * The `FineTune` object represents a fine-tuning job that has been created through
+ * the API.
+ */
 export interface FineTune {
+  /**
+   * The object identifier, which can be referenced in the API endpoints.
+   */
   id: string;
 
+  /**
+   * The unix timestamp for when the fine-tuning job was created.
+   */
   created_at: number;
 
+  /**
+   * The name of the fine-tuned model that is being created.
+   */
   fine_tuned_model: string | null;
 
+  /**
+   * The hyperparameters used for the fine-tuning job. See the
+   * [Fine-tuning Guide](/docs/guides/fine-tuning/hyperparameters) for more details.
+   */
   hyperparams: FineTune.Hyperparams;
 
+  /**
+   * The base model that is being fine-tuned.
+   */
   model: string;
 
+  /**
+   * The object type, which is always "fine-tune".
+   */
   object: string;
 
+  /**
+   * The organization that owns the fine-tuning job.
+   */
   organization_id: string;
 
+  /**
+   * The compiled results files for the fine-tuning job.
+   */
   result_files: Array<Files.FileObject>;
 
+  /**
+   * The current status of the fine-tuning job, which can be either `created`,
+   * `pending`, `running`, `succeeded`, `failed`, or `cancelled`.
+   */
   status: string;
 
+  /**
+   * The list of files used for training.
+   */
   training_files: Array<Files.FileObject>;
 
+  /**
+   * The unix timestamp for when the fine-tuning job was last updated.
+   */
   updated_at: number;
 
+  /**
+   * The list of files used for validation.
+   */
   validation_files: Array<Files.FileObject>;
 
+  /**
+   * The list of events that have been observed in the lifecycle of the FineTune job.
+   */
   events?: Array<FineTuneEvent>;
 }
 
 export namespace FineTune {
+  /**
+   * The hyperparameters used for the fine-tuning job. See the
+   * [Fine-tuning Guide](/docs/guides/fine-tuning/hyperparameters) for more details.
+   */
   export interface Hyperparams {
+    /**
+     * The batch size to use for training. The batch size is the number of training
+     * examples used to train a single forward and backward pass.
+     */
     batch_size: number;
 
+    /**
+     * The learning rate multiplier to use for training.
+     */
     learning_rate_multiplier: number;
 
+    /**
+     * The number of epochs to train the model for. An epoch refers to one full cycle
+     * through the training dataset.
+     */
     n_epochs: number;
 
+    /**
+     * The weight to use for loss on the prompt tokens.
+     */
     prompt_loss_weight: number;
 
+    /**
+     * The number of classes to use for computing classification metrics.
+     */
     classification_n_classes?: number;
 
+    /**
+     * The positive class to use for computing classification metrics.
+     */
     classification_positive_class?: string;
 
+    /**
+     * The classification metrics to compute using the validation dataset at the end of
+     * every epoch.
+     */
     compute_classification_metrics?: boolean;
   }
 }

src/resources/images.ts

@@ -31,9 +31,19 @@ export class Images extends APIResource {
   }
 }
 
+/**
+ * Represents the url or the content of an image generated by the OpenAI API.
+ */
 export interface Image {
+  /**
+   * The base64-encoded JSON of the generated image, if `response_format` is
+   * `b64_json`.
+   */
   b64_json?: string;
 
+  /**
+   * The URL of the generated image, if `response_format` is `url` (default).
+   */
   url?: string;
 }
 

src/resources/index.ts

@@ -5,13 +5,14 @@ export { Chat } from './chat/chat';
 export {
   Completion,
   CompletionChoice,
+  CompletionUsage,
   CompletionCreateParams,
   CompletionCreateParamsNonStreaming,
   CompletionCreateParamsStreaming,
   Completions,
 } from './completions';
+export { CreateEmbeddingResponse, Embedding, EmbeddingCreateParams, Embeddings } from './embeddings';
 export { Edit, EditCreateParams, Edits } from './edits';
-export { Embedding, EmbeddingCreateParams, Embeddings } from './embeddings';
 export { FileContent, FileDeleted, FileObject, FileCreateParams, FileObjectsPage, Files } from './files';
 export {
   FineTune,

src/resources/models.ts

@@ -37,13 +37,28 @@ export class ModelsPage extends Page<Model> {}
 // alias so we can export it in the namespace
 type _ModelsPage = ModelsPage;
 
+/**
+ * Describes an OpenAI model offering that can be used with the API.
+ */
 export interface Model {
+  /**
+   * The model identifier, which can be referenced in the API endpoints.
+   */
   id: string;
 
+  /**
+   * The date and time when the model was created.
+   */
   created: number;
 
+  /**
+   * The object type, which is always "model".
+   */
   object: string;
 
+  /**
+   * The organization that owns the model.
+   */
   owned_by: string;
 }
 

src/resources/moderations.ts

@@ -17,52 +17,123 @@ export class Moderations extends APIResource {
 }
 
 export interface Moderation {
+  /**
+   * A list of the categories, and whether they are flagged or not.
+   */
   categories: Moderation.Categories;
 
+  /**
+   * A list of the categories along with their scores as predicted by model.
+   */
   category_scores: Moderation.CategoryScores;
 
+  /**
+   * Whether the content violates
+   * [OpenAI's usage policies](/policies/usage-policies).
+   */
   flagged: boolean;
 }
 
 export namespace Moderation {
+  /**
+   * A list of the categories, and whether they are flagged or not.
+   */
   export interface Categories {
+    /**
+     * Whether the content was flagged as 'hate'.
+     */
     hate: boolean;
 
+    /**
+     * Whether the content was flagged as 'hate/threatening'.
+     */
     'hate/threatening': boolean;
 
+    /**
+     * Whether the content was flagged as 'self-harm'.
+     */
     'self-harm': boolean;
 
+    /**
+     * Whether the content was flagged as 'sexual'.
+     */
     sexual: boolean;
 
+    /**
+     * Whether the content was flagged as 'sexual/minors'.
+     */
     'sexual/minors': boolean;
 
+    /**
+     * Whether the content was flagged as 'violence'.
+     */
     violence: boolean;
 
+    /**
+     * Whether the content was flagged as 'violence/graphic'.
+     */
     'violence/graphic': boolean;
   }
 
+  /**
+   * A list of the categories along with their scores as predicted by model.
+   */
   export interface CategoryScores {
+    /**
+     * The score for the category 'hate'.
+     */
     hate: number;
 
+    /**
+     * The score for the category 'hate/threatening'.
+     */
     'hate/threatening': number;
 
+    /**
+     * The score for the category 'self-harm'.
+     */
     'self-harm': number;
 
+    /**
+     * The score for the category 'sexual'.
+     */
     sexual: number;
 
+    /**
+     * The score for the category 'sexual/minors'.
+     */
     'sexual/minors': number;
 
+    /**
+     * The score for the category 'violence'.
+     */
     violence: number;
 
+    /**
+     * The score for the category 'violence/graphic'.
+     */
     'violence/graphic': number;
   }
 }
 
+/**
+ * Represents policy compliance report by OpenAI's content moderation model against
+ * a given input.
+ */
 export interface ModerationCreateResponse {
+  /**
+   * The unique identifier for the moderation request.
+   */
   id: string;
 
+  /**
+   * The model used to generate the moderation results.
+   */
   model: string;
 
+  /**
+   * A list of moderation objects.
+   */
   results: Array<Moderation>;
 }
 

src/version.ts

@@ -1 +1 @@
-export const VERSION = '4.0.0-beta.10';
+export const VERSION = '4.0.0-beta.11';