docs(api): enhance method docstrings across audio/chat/completion/skill/upload/video APIs

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 135
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-0db5326a0fb6a30ffad9242c72872c3388ef927e8a4549ddd20aec3420541209.yml
-openapi_spec_hash: 9523fe30739802e15c88f4e7aac44e7f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-c20486f46004d6be2d280d7792c64d47fcea3e5b7fbbb50d3ffc6241aba653df.yml
+openapi_spec_hash: bf1dbabc5a923d897309273183525c02
 config_hash: 948733484caf41e71093c6582dbc319c

audiospeech.go

@@ -33,6 +33,8 @@ func NewAudioSpeechService(opts ...option.RequestOption) (r AudioSpeechService)
 }
 
 // Generates audio from the input text.
+//
+// Returns the audio file content, or a stream of audio events.
 func (r *AudioSpeechService) New(ctx context.Context, body AudioSpeechNewParams, opts ...option.RequestOption) (res *http.Response, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/octet-stream")}, opts...)

audiotranscription.go

@@ -41,6 +41,9 @@ func NewAudioTranscriptionService(opts ...option.RequestOption) (r AudioTranscri
 }
 
 // Transcribes audio into the input language.
+//
+// Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+// format, or a stream of transcript events.
 func (r *AudioTranscriptionService) New(ctx context.Context, body AudioTranscriptionNewParams, opts ...option.RequestOption) (res *AudioTranscriptionNewResponseUnion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "audio/transcriptions"
@@ -49,6 +52,9 @@ func (r *AudioTranscriptionService) New(ctx context.Context, body AudioTranscrip
 }
 
 // Transcribes audio into the input language.
+//
+// Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
+// format, or a stream of transcript events.
 func (r *AudioTranscriptionService) NewStreaming(ctx context.Context, body AudioTranscriptionNewParams, opts ...option.RequestOption) (stream *ssestream.Stream[TranscriptionStreamEventUnion]) {
 	var (
 		raw *http.Response

betachatkitsession.go

@@ -34,7 +34,7 @@ func NewBetaChatKitSessionService(opts ...option.RequestOption) (r BetaChatKitSe
 	return
 }
 
-// Create a ChatKit session
+// Create a ChatKit session.
 func (r *BetaChatKitSessionService) New(ctx context.Context, body BetaChatKitSessionNewParams, opts ...option.RequestOption) (res *ChatSession, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("OpenAI-Beta", "chatkit_beta=v1")}, opts...)
@@ -43,7 +43,9 @@ func (r *BetaChatKitSessionService) New(ctx context.Context, body BetaChatKitSes
 	return
 }
 
-// Cancel a ChatKit session
+// Cancel an active ChatKit session and return its most recent metadata.
+//
+// Cancelling prevents new requests from using the issued client secret.
 func (r *BetaChatKitSessionService) Cancel(ctx context.Context, sessionID string, opts ...option.RequestOption) (res *ChatSession, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("OpenAI-Beta", "chatkit_beta=v1")}, opts...)

betachatkitthread.go

@@ -40,7 +40,7 @@ func NewBetaChatKitThreadService(opts ...option.RequestOption) (r BetaChatKitThr
 	return
 }
 
-// Retrieve a ChatKit thread
+// Retrieve a ChatKit thread by its identifier.
 func (r *BetaChatKitThreadService) Get(ctx context.Context, threadID string, opts ...option.RequestOption) (res *ChatKitThread, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("OpenAI-Beta", "chatkit_beta=v1")}, opts...)
@@ -53,7 +53,7 @@ func (r *BetaChatKitThreadService) Get(ctx context.Context, threadID string, opt
 	return
 }
 
-// List ChatKit threads
+// List ChatKit threads with optional pagination and user filters.
 func (r *BetaChatKitThreadService) List(ctx context.Context, query BetaChatKitThreadListParams, opts ...option.RequestOption) (res *pagination.ConversationCursorPage[ChatKitThread], err error) {
 	var raw *http.Response
 	opts = slices.Concat(r.Options, opts)
@@ -71,12 +71,12 @@ func (r *BetaChatKitThreadService) List(ctx context.Context, query BetaChatKitTh
 	return res, nil
 }
 
-// List ChatKit threads
+// List ChatKit threads with optional pagination and user filters.
 func (r *BetaChatKitThreadService) ListAutoPaging(ctx context.Context, query BetaChatKitThreadListParams, opts ...option.RequestOption) *pagination.ConversationCursorPageAutoPager[ChatKitThread] {
 	return pagination.NewConversationCursorPageAutoPager(r.List(ctx, query, opts...))
 }
 
-// Delete a ChatKit thread
+// Delete a ChatKit thread along with its items and stored attachments.
 func (r *BetaChatKitThreadService) Delete(ctx context.Context, threadID string, opts ...option.RequestOption) (res *BetaChatKitThreadDeleteResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("OpenAI-Beta", "chatkit_beta=v1")}, opts...)
@@ -89,7 +89,7 @@ func (r *BetaChatKitThreadService) Delete(ctx context.Context, threadID string,
 	return
 }
 
-// List ChatKit thread items
+// List items that belong to a ChatKit thread.
 func (r *BetaChatKitThreadService) ListItems(ctx context.Context, threadID string, query BetaChatKitThreadListItemsParams, opts ...option.RequestOption) (res *pagination.ConversationCursorPage[ChatKitThreadItemListDataUnion], err error) {
 	var raw *http.Response
 	opts = slices.Concat(r.Options, opts)
@@ -111,7 +111,7 @@ func (r *BetaChatKitThreadService) ListItems(ctx context.Context, threadID strin
 	return res, nil
 }
 
-// List ChatKit thread items
+// List items that belong to a ChatKit thread.
 func (r *BetaChatKitThreadService) ListItemsAutoPaging(ctx context.Context, threadID string, query BetaChatKitThreadListItemsParams, opts ...option.RequestOption) *pagination.ConversationCursorPageAutoPager[ChatKitThreadItemListDataUnion] {
 	return pagination.NewConversationCursorPageAutoPager(r.ListItems(ctx, threadID, query, opts...))
 }

chatcompletion.go

@@ -61,6 +61,9 @@ func NewChatCompletionService(opts ...option.RequestOption) (r ChatCompletionSer
 // supported for reasoning models are noted below. For the current state of
 // unsupported parameters in reasoning models,
 // [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+//
+// Returns a chat completion object, or a streamed sequence of chat completion
+// chunk objects if the request is streamed.
 func (r *ChatCompletionService) New(ctx context.Context, body ChatCompletionNewParams, opts ...option.RequestOption) (res *ChatCompletion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "chat/completions"
@@ -85,6 +88,9 @@ func (r *ChatCompletionService) New(ctx context.Context, body ChatCompletionNewP
 // supported for reasoning models are noted below. For the current state of
 // unsupported parameters in reasoning models,
 // [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+//
+// Returns a chat completion object, or a streamed sequence of chat completion
+// chunk objects if the request is streamed.
 func (r *ChatCompletionService) NewStreaming(ctx context.Context, body ChatCompletionNewParams, opts ...option.RequestOption) (stream *ssestream.Stream[ChatCompletionChunk]) {
 	var (
 		raw *http.Response

completion.go

@@ -36,6 +36,9 @@ func NewCompletionService(opts ...option.RequestOption) (r CompletionService) {
 }
 
 // Creates a completion for the provided prompt and parameters.
+//
+// Returns a completion object, or a sequence of completion objects if the request
+// is streamed.
 func (r *CompletionService) New(ctx context.Context, body CompletionNewParams, opts ...option.RequestOption) (res *Completion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "completions"
@@ -44,6 +47,9 @@ func (r *CompletionService) New(ctx context.Context, body CompletionNewParams, o
 }
 
 // Creates a completion for the provided prompt and parameters.
+//
+// Returns a completion object, or a sequence of completion objects if the request
+// is streamed.
 func (r *CompletionService) NewStreaming(ctx context.Context, body CompletionNewParams, opts ...option.RequestOption) (stream *ssestream.Stream[Completion]) {
 	var (
 		raw *http.Response

realtime/clientsecret.go

@@ -37,6 +37,20 @@ func NewClientSecretService(opts ...option.RequestOption) (r ClientSecretService
 }
 
 // Create a Realtime client secret with an associated session configuration.
+//
+// Client secrets are short-lived tokens that can be passed to a client app, such
+// as a web frontend or mobile client, which grants access to the Realtime API
+// without leaking your main API key. You can configure a custom TTL for each
+// client secret.
+//
+// You can also attach session configuration options to the client secret, which
+// will be applied to any sessions created using that client secret, but these can
+// also be overridden by the client connection.
+//
+// [Learn more about authentication with client secrets over WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+//
+// Returns the created client secret and the effective session object. The client
+// secret is a string that looks like `ek_1234`.
 func (r *ClientSecretService) New(ctx context.Context, body ClientSecretNewParams, opts ...option.RequestOption) (res *ClientSecretNewResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "realtime/client_secrets"

responses/inputtoken.go

@@ -35,7 +35,10 @@ func NewInputTokenService(opts ...option.RequestOption) (r InputTokenService) {
 	return
 }
 
-// Get input token counts
+// Returns input token counts of the request.
+//
+// Returns an object with `object` set to `response.input_tokens` and an
+// `input_tokens` count.
 func (r *InputTokenService) Count(ctx context.Context, body InputTokenCountParams, opts ...option.RequestOption) (res *InputTokenCountResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "responses/input_tokens"

responses/response.go

@@ -144,7 +144,12 @@ func (r *ResponseService) Cancel(ctx context.Context, responseID string, opts ..
 	return
 }
 
-// Compact conversation
+// Compact a conversation. Returns a compacted response object.
+//
+// Learn when and how to compact long-running conversations in the
+// [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window).
+// For ZDR-compatible compaction details, see
+// [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).
 func (r *ResponseService) Compact(ctx context.Context, body ResponseCompactParams, opts ...option.RequestOption) (res *CompactedResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "responses/compact"

skill.go

@@ -47,7 +47,7 @@ func NewSkillService(opts ...option.RequestOption) (r SkillService) {
 	return
 }
 
-// Create Skill
+// Create a new skill.
 func (r *SkillService) New(ctx context.Context, body SkillNewParams, opts ...option.RequestOption) (res *Skill, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "skills"
@@ -55,7 +55,7 @@ func (r *SkillService) New(ctx context.Context, body SkillNewParams, opts ...opt
 	return
 }
 
-// Get Skill
+// Get a skill by its ID.
 func (r *SkillService) Get(ctx context.Context, skillID string, opts ...option.RequestOption) (res *Skill, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {
@@ -67,7 +67,7 @@ func (r *SkillService) Get(ctx context.Context, skillID string, opts ...option.R
 	return
 }
 
-// Update Skill Default Version
+// Update the default version pointer for a skill.
 func (r *SkillService) Update(ctx context.Context, skillID string, body SkillUpdateParams, opts ...option.RequestOption) (res *Skill, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {
@@ -79,7 +79,7 @@ func (r *SkillService) Update(ctx context.Context, skillID string, body SkillUpd
 	return
 }
 
-// List Skills
+// List all skills for the current project.
 func (r *SkillService) List(ctx context.Context, query SkillListParams, opts ...option.RequestOption) (res *pagination.CursorPage[Skill], err error) {
 	var raw *http.Response
 	opts = slices.Concat(r.Options, opts)
@@ -97,12 +97,12 @@ func (r *SkillService) List(ctx context.Context, query SkillListParams, opts ...
 	return res, nil
 }
 
-// List Skills
+// List all skills for the current project.
 func (r *SkillService) ListAutoPaging(ctx context.Context, query SkillListParams, opts ...option.RequestOption) *pagination.CursorPageAutoPager[Skill] {
 	return pagination.NewCursorPageAutoPager(r.List(ctx, query, opts...))
 }
 
-// Delete Skill
+// Delete a skill by its ID.
 func (r *SkillService) Delete(ctx context.Context, skillID string, opts ...option.RequestOption) (res *DeletedSkill, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {

skillcontent.go

@@ -32,7 +32,7 @@ func NewSkillContentService(opts ...option.RequestOption) (r SkillContentService
 	return
 }
 
-// Get Skill Content
+// Download a skill zip bundle by its ID.
 func (r *SkillContentService) Get(ctx context.Context, skillID string, opts ...option.RequestOption) (res *http.Response, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/binary")}, opts...)

skillversion.go

@@ -45,7 +45,7 @@ func NewSkillVersionService(opts ...option.RequestOption) (r SkillVersionService
 	return
 }
 
-// Create Skill Version
+// Create a new immutable skill version.
 func (r *SkillVersionService) New(ctx context.Context, skillID string, body SkillVersionNewParams, opts ...option.RequestOption) (res *SkillVersion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {
@@ -57,7 +57,7 @@ func (r *SkillVersionService) New(ctx context.Context, skillID string, body Skil
 	return
 }
 
-// Get Skill Version
+// Get a specific skill version.
 func (r *SkillVersionService) Get(ctx context.Context, skillID string, version string, opts ...option.RequestOption) (res *SkillVersion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {
@@ -73,7 +73,7 @@ func (r *SkillVersionService) Get(ctx context.Context, skillID string, version s
 	return
 }
 
-// List Skill Versions
+// List skill versions for a skill.
 func (r *SkillVersionService) List(ctx context.Context, skillID string, query SkillVersionListParams, opts ...option.RequestOption) (res *pagination.CursorPage[SkillVersion], err error) {
 	var raw *http.Response
 	opts = slices.Concat(r.Options, opts)
@@ -95,12 +95,12 @@ func (r *SkillVersionService) List(ctx context.Context, skillID string, query Sk
 	return res, nil
 }
 
-// List Skill Versions
+// List skill versions for a skill.
 func (r *SkillVersionService) ListAutoPaging(ctx context.Context, skillID string, query SkillVersionListParams, opts ...option.RequestOption) *pagination.CursorPageAutoPager[SkillVersion] {
 	return pagination.NewCursorPageAutoPager(r.List(ctx, skillID, query, opts...))
 }
 
-// Delete Skill Version
+// Delete a skill version.
 func (r *SkillVersionService) Delete(ctx context.Context, skillID string, version string, opts ...option.RequestOption) (res *DeletedSkillVersion, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if skillID == "" {

skillversioncontent.go

@@ -32,7 +32,7 @@ func NewSkillVersionContentService(opts ...option.RequestOption) (r SkillVersion
 	return
 }
 
-// Get Skill Version Content
+// Download a skill version zip bundle.
 func (r *SkillVersionContentService) Get(ctx context.Context, skillID string, version string, opts ...option.RequestOption) (res *http.Response, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/binary")}, opts...)

upload.go

@@ -57,6 +57,8 @@ func NewUploadService(opts ...option.RequestOption) (r UploadService) {
 // For guidance on the proper filename extensions for each purpose, please follow
 // the documentation on
 // [creating a File](https://platform.openai.com/docs/api-reference/files/create).
+//
+// Returns the Upload object with status `pending`.
 func (r *UploadService) New(ctx context.Context, body UploadNewParams, opts ...option.RequestOption) (res *Upload, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "uploads"
@@ -65,6 +67,8 @@ func (r *UploadService) New(ctx context.Context, body UploadNewParams, opts ...o
 }
 
 // Cancels the Upload. No Parts may be added after an Upload is cancelled.
+//
+// Returns the Upload object with status `cancelled`.
 func (r *UploadService) Cancel(ctx context.Context, uploadID string, opts ...option.RequestOption) (res *Upload, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if uploadID == "" {
@@ -88,7 +92,9 @@ func (r *UploadService) Cancel(ctx context.Context, uploadID string, opts ...opt
 //
 // The number of bytes uploaded upon completion must match the number of bytes
 // initially specified when creating the Upload object. No Parts may be added after
-// an Upload is completed.
+// an Upload is completed. Returns the Upload object with status `completed`,
+// including an additional `file` property containing the created usable File
+// object.
 func (r *UploadService) Complete(ctx context.Context, uploadID string, body UploadCompleteParams, opts ...option.RequestOption) (res *Upload, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if uploadID == "" {

video.go

@@ -43,7 +43,7 @@ func NewVideoService(opts ...option.RequestOption) (r VideoService) {
 	return
 }
 
-// Create a video
+// Create a new video generation job from a prompt and optional reference assets.
 func (r *VideoService) New(ctx context.Context, body VideoNewParams, opts ...option.RequestOption) (res *Video, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "videos"
@@ -63,7 +63,7 @@ func (r *VideoService) NewAndPoll(ctx context.Context, body VideoNewParams, poll
 	return r.PollStatus(ctx, video.ID, pollIntervalMs, opts...)
 }
 
-// Retrieve a video
+// Fetch the latest metadata for a generated video.
 func (r *VideoService) Get(ctx context.Context, videoID string, opts ...option.RequestOption) (res *Video, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if videoID == "" {
@@ -75,7 +75,7 @@ func (r *VideoService) Get(ctx context.Context, videoID string, opts ...option.R
 	return
 }
 
-// List videos
+// List recently generated videos for the current project.
 func (r *VideoService) List(ctx context.Context, query VideoListParams, opts ...option.RequestOption) (res *pagination.ConversationCursorPage[Video], err error) {
 	var raw *http.Response
 	opts = slices.Concat(r.Options, opts)
@@ -93,12 +93,12 @@ func (r *VideoService) List(ctx context.Context, query VideoListParams, opts ...
 	return res, nil
 }
 
-// List videos
+// List recently generated videos for the current project.
 func (r *VideoService) ListAutoPaging(ctx context.Context, query VideoListParams, opts ...option.RequestOption) *pagination.ConversationCursorPageAutoPager[Video] {
 	return pagination.NewConversationCursorPageAutoPager(r.List(ctx, query, opts...))
 }
 
-// Delete a video
+// Permanently delete a completed or failed video and its stored assets.
 func (r *VideoService) Delete(ctx context.Context, videoID string, opts ...option.RequestOption) (res *VideoDeleteResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if videoID == "" {
@@ -110,7 +110,9 @@ func (r *VideoService) Delete(ctx context.Context, videoID string, opts ...optio
 	return
 }
 
-// Download video content
+// Download the generated video bytes or a derived preview asset.
+//
+// Streams the rendered video content for the specified video job.
 func (r *VideoService) DownloadContent(ctx context.Context, videoID string, query VideoDownloadContentParams, opts ...option.RequestOption) (res *http.Response, err error) {
 	opts = slices.Concat(r.Options, opts)
 	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/binary")}, opts...)
@@ -123,7 +125,7 @@ func (r *VideoService) DownloadContent(ctx context.Context, videoID string, quer
 	return
 }
 
-// Create a video remix
+// Create a remix of a completed video using a refreshed prompt.
 func (r *VideoService) Remix(ctx context.Context, videoID string, body VideoRemixParams, opts ...option.RequestOption) (res *Video, err error) {
 	opts = slices.Concat(r.Options, opts)
 	if videoID == "" {