chore(api): update docs (#703)

src/resources/audio/speech.ts

@@ -35,13 +35,10 @@ export interface SpeechCreateParams {
   voice: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
 
   /**
-   * The format to return audio in. Supported formats are `mp3`, `opus`, `aac`,
-   * `flac`, `pcm`, and `wav`.
-   *
-   * The `pcm` audio format, similar to `wav` but without a header, utilizes a 24kHz
-   * sample rate, mono channel, and 16-bit depth in signed little-endian format.
+   * The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`,
+   * `wav`, and `pcm`.
    */
-  response_format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'pcm' | 'wav';
+  response_format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
 
   /**
    * The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is

src/resources/audio/transcriptions.ts

@@ -14,7 +14,14 @@ export class Transcriptions extends APIResource {
   }
 }
 
+/**
+ * Represents a transcription response returned by model, based on the provided
+ * input.
+ */
 export interface Transcription {
+  /**
+   * The transcribed text.
+   */
   text: string;
 }
 
@@ -26,7 +33,8 @@ export interface TranscriptionCreateParams {
   file: Uploadable;
 
   /**
-   * ID of the model to use. Only `whisper-1` is currently available.
+   * ID of the model to use. Only `whisper-1` (which is powered by our open source
+   * Whisper V2 model) is currently available.
    */
   model: (string & {}) | 'whisper-1';
 
@@ -61,9 +69,11 @@ export interface TranscriptionCreateParams {
   temperature?: number;
 
   /**
-   * The timestamp granularities to populate for this transcription. Any of these
-   * options: `word`, or `segment`. Note: There is no additional latency for segment
-   * timestamps, but generating word timestamps incurs additional latency.
+   * The timestamp granularities to populate for this transcription.
+   * `response_format` must be set `verbose_json` to use timestamp granularities.
+   * Either or both of these options are supported: `word`, or `segment`. Note: There
+   * is no additional latency for segment timestamps, but generating word timestamps
+   * incurs additional latency.
    */
   timestamp_granularities?: Array<'word' | 'segment'>;
 }

src/resources/audio/translations.ts

@@ -26,7 +26,8 @@ export interface TranslationCreateParams {
   file: Uploadable;
 
   /**
-   * ID of the model to use. Only `whisper-1` is currently available.
+   * ID of the model to use. Only `whisper-1` (which is powered by our open source
+   * Whisper V2 model) is currently available.
    */
   model: (string & {}) | 'whisper-1';
 

src/resources/beta/threads/runs/runs.ts

@@ -270,9 +270,9 @@ export namespace Run {
    */
   export interface LastError {
     /**
-     * One of `server_error` or `rate_limit_exceeded`.
+     * One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`.
      */
-    code: 'server_error' | 'rate_limit_exceeded';
+    code: 'server_error' | 'rate_limit_exceeded' | 'invalid_prompt';
 
     /**
      * A human-readable description of the error.

src/resources/chat/completions.ts

@@ -546,7 +546,9 @@ export interface ChatCompletionTokenLogprob {
   bytes: Array<number> | null;
 
   /**
-   * The log probability of this token.
+   * The log probability of this token, if it is within the top 20 most likely
+   * tokens. Otherwise, the value `-9999.0` is used to signify that the token is very
+   * unlikely.
    */
   logprob: number;
 
@@ -574,7 +576,9 @@ export namespace ChatCompletionTokenLogprob {
     bytes: Array<number> | null;
 
     /**
-     * The log probability of this token.
+     * The log probability of this token, if it is within the top 20 most likely
+     * tokens. Otherwise, the value `-9999.0` is used to signify that the token is very
+     * unlikely.
      */
     logprob: number;
   }
@@ -827,9 +831,9 @@ export interface ChatCompletionCreateParamsBase {
   tools?: Array<ChatCompletionTool>;
 
   /**
-   * An integer between 0 and 5 specifying the number of most likely tokens to return
-   * at each token position, each with an associated log probability. `logprobs` must
-   * be set to `true` if this parameter is used.
+   * An integer between 0 and 20 specifying the number of most likely tokens to
+   * return at each token position, each with an associated log probability.
+   * `logprobs` must be set to `true` if this parameter is used.
    */
   top_logprobs?: number | null;
 

src/resources/images.ts

@@ -80,7 +80,8 @@ export interface ImageCreateVariationParams {
 
   /**
    * The format in which the generated images are returned. Must be one of `url` or
-   * `b64_json`.
+   * `b64_json`. URLs are only valid for 60 minutes after the image has been
+   * generated.
    */
   response_format?: 'url' | 'b64_json' | null;
 
@@ -131,7 +132,8 @@ export interface ImageEditParams {
 
   /**
    * The format in which the generated images are returned. Must be one of `url` or
-   * `b64_json`.
+   * `b64_json`. URLs are only valid for 60 minutes after the image has been
+   * generated.
    */
   response_format?: 'url' | 'b64_json' | null;
 
@@ -176,7 +178,8 @@ export interface ImageGenerateParams {
 
   /**
    * The format in which the generated images are returned. Must be one of `url` or
-   * `b64_json`.
+   * `b64_json`. URLs are only valid for 60 minutes after the image has been
+   * generated.
    */
   response_format?: 'url' | 'b64_json' | null;
 

src/resources/moderations.ts

@@ -6,7 +6,7 @@ import * as ModerationsAPI from 'openai/resources/moderations';
 
 export class Moderations extends APIResource {
   /**
-   * Classifies if text violates OpenAI's Content Policy
+   * Classifies if text is potentially harmful.
    */
   create(
     body: ModerationCreateParams,
@@ -28,8 +28,7 @@ export interface Moderation {
   category_scores: Moderation.CategoryScores;
 
   /**
-   * Whether the content violates
-   * [OpenAI's usage policies](/policies/usage-policies).
+   * Whether any of the below categories are flagged.
    */
   flagged: boolean;
 }
@@ -170,8 +169,7 @@ export namespace Moderation {
 }
 
 /**
- * Represents policy compliance report by OpenAI's content moderation model against
- * a given input.
+ * Represents if a given text input is potentially harmful.
  */
 export interface ModerationCreateResponse {
   /**