1// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3package openai
4
5import (
6 "context"
7 "net/http"
8
9 "github.com/openai/openai-go/internal/apijson"
10 "github.com/openai/openai-go/internal/requestconfig"
11 "github.com/openai/openai-go/option"
12 "github.com/openai/openai-go/packages/param"
13 "github.com/openai/openai-go/packages/resp"
14 "github.com/openai/openai-go/packages/ssestream"
15 "github.com/openai/openai-go/shared/constant"
16)
17
18// CompletionService contains methods and other services that help with interacting
19// with the openai API.
20//
21// Note, unlike clients, this service does not read variables from the environment
22// automatically. You should not instantiate this service directly, and instead use
23// the [NewCompletionService] method instead.
24type CompletionService struct {
25 Options []option.RequestOption
26}
27
28// NewCompletionService generates a new service that applies the given options to
29// each request. These options are applied after the parent client's options (if
30// there is one), and before any request-specific options.
31func NewCompletionService(opts ...option.RequestOption) (r CompletionService) {
32 r = CompletionService{}
33 r.Options = opts
34 return
35}
36
37// Creates a completion for the provided prompt and parameters.
38func (r *CompletionService) New(ctx context.Context, body CompletionNewParams, opts ...option.RequestOption) (res *Completion, err error) {
39 opts = append(r.Options[:], opts...)
40 path := "completions"
41 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
42 return
43}
44
45// Creates a completion for the provided prompt and parameters.
46func (r *CompletionService) NewStreaming(ctx context.Context, body CompletionNewParams, opts ...option.RequestOption) (stream *ssestream.Stream[Completion]) {
47 var (
48 raw *http.Response
49 err error
50 )
51 opts = append(r.Options[:], opts...)
52 opts = append([]option.RequestOption{option.WithJSONSet("stream", true)}, opts...)
53 path := "completions"
54 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &raw, opts...)
55 return ssestream.NewStream[Completion](ssestream.NewDecoder(raw), err)
56}
57
58// Represents a completion response from the API. Note: both the streamed and
59// non-streamed response objects share the same shape (unlike the chat endpoint).
60type Completion struct {
61 // A unique identifier for the completion.
62 ID string `json:"id,required"`
63 // The list of completion choices the model generated for the input prompt.
64 Choices []CompletionChoice `json:"choices,required"`
65 // The Unix timestamp (in seconds) of when the completion was created.
66 Created int64 `json:"created,required"`
67 // The model used for completion.
68 Model string `json:"model,required"`
69 // The object type, which is always "text_completion"
70 Object constant.TextCompletion `json:"object,required"`
71 // This fingerprint represents the backend configuration that the model runs with.
72 //
73 // Can be used in conjunction with the `seed` request parameter to understand when
74 // backend changes have been made that might impact determinism.
75 SystemFingerprint string `json:"system_fingerprint"`
76 // Usage statistics for the completion request.
77 Usage CompletionUsage `json:"usage"`
78 // Metadata for the response, check the presence of optional fields with the
79 // [resp.Field.IsPresent] method.
80 JSON struct {
81 ID resp.Field
82 Choices resp.Field
83 Created resp.Field
84 Model resp.Field
85 Object resp.Field
86 SystemFingerprint resp.Field
87 Usage resp.Field
88 ExtraFields map[string]resp.Field
89 raw string
90 } `json:"-"`
91}
92
93// Returns the unmodified JSON received from the API
94func (r Completion) RawJSON() string { return r.JSON.raw }
95func (r *Completion) UnmarshalJSON(data []byte) error {
96 return apijson.UnmarshalRoot(data, r)
97}
98
99type CompletionChoice struct {
100 // The reason the model stopped generating tokens. This will be `stop` if the model
101 // hit a natural stop point or a provided stop sequence, `length` if the maximum
102 // number of tokens specified in the request was reached, or `content_filter` if
103 // content was omitted due to a flag from our content filters.
104 //
105 // Any of "stop", "length", "content_filter".
106 FinishReason CompletionChoiceFinishReason `json:"finish_reason,required"`
107 Index int64 `json:"index,required"`
108 Logprobs CompletionChoiceLogprobs `json:"logprobs,required"`
109 Text string `json:"text,required"`
110 // Metadata for the response, check the presence of optional fields with the
111 // [resp.Field.IsPresent] method.
112 JSON struct {
113 FinishReason resp.Field
114 Index resp.Field
115 Logprobs resp.Field
116 Text resp.Field
117 ExtraFields map[string]resp.Field
118 raw string
119 } `json:"-"`
120}
121
122// Returns the unmodified JSON received from the API
123func (r CompletionChoice) RawJSON() string { return r.JSON.raw }
124func (r *CompletionChoice) UnmarshalJSON(data []byte) error {
125 return apijson.UnmarshalRoot(data, r)
126}
127
128// The reason the model stopped generating tokens. This will be `stop` if the model
129// hit a natural stop point or a provided stop sequence, `length` if the maximum
130// number of tokens specified in the request was reached, or `content_filter` if
131// content was omitted due to a flag from our content filters.
132type CompletionChoiceFinishReason string
133
134const (
135 CompletionChoiceFinishReasonStop CompletionChoiceFinishReason = "stop"
136 CompletionChoiceFinishReasonLength CompletionChoiceFinishReason = "length"
137 CompletionChoiceFinishReasonContentFilter CompletionChoiceFinishReason = "content_filter"
138)
139
140type CompletionChoiceLogprobs struct {
141 TextOffset []int64 `json:"text_offset"`
142 TokenLogprobs []float64 `json:"token_logprobs"`
143 Tokens []string `json:"tokens"`
144 TopLogprobs []map[string]float64 `json:"top_logprobs"`
145 // Metadata for the response, check the presence of optional fields with the
146 // [resp.Field.IsPresent] method.
147 JSON struct {
148 TextOffset resp.Field
149 TokenLogprobs resp.Field
150 Tokens resp.Field
151 TopLogprobs resp.Field
152 ExtraFields map[string]resp.Field
153 raw string
154 } `json:"-"`
155}
156
157// Returns the unmodified JSON received from the API
158func (r CompletionChoiceLogprobs) RawJSON() string { return r.JSON.raw }
159func (r *CompletionChoiceLogprobs) UnmarshalJSON(data []byte) error {
160 return apijson.UnmarshalRoot(data, r)
161}
162
163// Usage statistics for the completion request.
164type CompletionUsage struct {
165 // Number of tokens in the generated completion.
166 CompletionTokens int64 `json:"completion_tokens,required"`
167 // Number of tokens in the prompt.
168 PromptTokens int64 `json:"prompt_tokens,required"`
169 // Total number of tokens used in the request (prompt + completion).
170 TotalTokens int64 `json:"total_tokens,required"`
171 // Breakdown of tokens used in a completion.
172 CompletionTokensDetails CompletionUsageCompletionTokensDetails `json:"completion_tokens_details"`
173 // Breakdown of tokens used in the prompt.
174 PromptTokensDetails CompletionUsagePromptTokensDetails `json:"prompt_tokens_details"`
175 // Metadata for the response, check the presence of optional fields with the
176 // [resp.Field.IsPresent] method.
177 JSON struct {
178 CompletionTokens resp.Field
179 PromptTokens resp.Field
180 TotalTokens resp.Field
181 CompletionTokensDetails resp.Field
182 PromptTokensDetails resp.Field
183 ExtraFields map[string]resp.Field
184 raw string
185 } `json:"-"`
186}
187
188// Returns the unmodified JSON received from the API
189func (r CompletionUsage) RawJSON() string { return r.JSON.raw }
190func (r *CompletionUsage) UnmarshalJSON(data []byte) error {
191 return apijson.UnmarshalRoot(data, r)
192}
193
194// Breakdown of tokens used in a completion.
195type CompletionUsageCompletionTokensDetails struct {
196 // When using Predicted Outputs, the number of tokens in the prediction that
197 // appeared in the completion.
198 AcceptedPredictionTokens int64 `json:"accepted_prediction_tokens"`
199 // Audio input tokens generated by the model.
200 AudioTokens int64 `json:"audio_tokens"`
201 // Tokens generated by the model for reasoning.
202 ReasoningTokens int64 `json:"reasoning_tokens"`
203 // When using Predicted Outputs, the number of tokens in the prediction that did
204 // not appear in the completion. However, like reasoning tokens, these tokens are
205 // still counted in the total completion tokens for purposes of billing, output,
206 // and context window limits.
207 RejectedPredictionTokens int64 `json:"rejected_prediction_tokens"`
208 // Metadata for the response, check the presence of optional fields with the
209 // [resp.Field.IsPresent] method.
210 JSON struct {
211 AcceptedPredictionTokens resp.Field
212 AudioTokens resp.Field
213 ReasoningTokens resp.Field
214 RejectedPredictionTokens resp.Field
215 ExtraFields map[string]resp.Field
216 raw string
217 } `json:"-"`
218}
219
220// Returns the unmodified JSON received from the API
221func (r CompletionUsageCompletionTokensDetails) RawJSON() string { return r.JSON.raw }
222func (r *CompletionUsageCompletionTokensDetails) UnmarshalJSON(data []byte) error {
223 return apijson.UnmarshalRoot(data, r)
224}
225
226// Breakdown of tokens used in the prompt.
227type CompletionUsagePromptTokensDetails struct {
228 // Audio input tokens present in the prompt.
229 AudioTokens int64 `json:"audio_tokens"`
230 // Cached tokens present in the prompt.
231 CachedTokens int64 `json:"cached_tokens"`
232 // Metadata for the response, check the presence of optional fields with the
233 // [resp.Field.IsPresent] method.
234 JSON struct {
235 AudioTokens resp.Field
236 CachedTokens resp.Field
237 ExtraFields map[string]resp.Field
238 raw string
239 } `json:"-"`
240}
241
242// Returns the unmodified JSON received from the API
243func (r CompletionUsagePromptTokensDetails) RawJSON() string { return r.JSON.raw }
244func (r *CompletionUsagePromptTokensDetails) UnmarshalJSON(data []byte) error {
245 return apijson.UnmarshalRoot(data, r)
246}
247
248type CompletionNewParams struct {
249 // The prompt(s) to generate completions for, encoded as a string, array of
250 // strings, array of tokens, or array of token arrays.
251 //
252 // Note that <|endoftext|> is the document separator that the model sees during
253 // training, so if a prompt is not specified the model will generate as if from the
254 // beginning of a new document.
255 Prompt CompletionNewParamsPromptUnion `json:"prompt,omitzero,required"`
256 // ID of the model to use. You can use the
257 // [List models](https://platform.openai.com/docs/api-reference/models/list) API to
258 // see all of your available models, or see our
259 // [Model overview](https://platform.openai.com/docs/models) for descriptions of
260 // them.
261 Model string `json:"model,omitzero,required"`
262 // Generates `best_of` completions server-side and returns the "best" (the one with
263 // the highest log probability per token). Results cannot be streamed.
264 //
265 // When used with `n`, `best_of` controls the number of candidate completions and
266 // `n` specifies how many to return – `best_of` must be greater than `n`.
267 //
268 // **Note:** Because this parameter generates many completions, it can quickly
269 // consume your token quota. Use carefully and ensure that you have reasonable
270 // settings for `max_tokens` and `stop`.
271 BestOf param.Opt[int64] `json:"best_of,omitzero"`
272 // Echo back the prompt in addition to the completion
273 Echo param.Opt[bool] `json:"echo,omitzero"`
274 // Number between -2.0 and 2.0. Positive values penalize new tokens based on their
275 // existing frequency in the text so far, decreasing the model's likelihood to
276 // repeat the same line verbatim.
277 //
278 // [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
279 FrequencyPenalty param.Opt[float64] `json:"frequency_penalty,omitzero"`
280 // Include the log probabilities on the `logprobs` most likely output tokens, as
281 // well the chosen tokens. For example, if `logprobs` is 5, the API will return a
282 // list of the 5 most likely tokens. The API will always return the `logprob` of
283 // the sampled token, so there may be up to `logprobs+1` elements in the response.
284 //
285 // The maximum value for `logprobs` is 5.
286 Logprobs param.Opt[int64] `json:"logprobs,omitzero"`
287 // The maximum number of [tokens](/tokenizer) that can be generated in the
288 // completion.
289 //
290 // The token count of your prompt plus `max_tokens` cannot exceed the model's
291 // context length.
292 // [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
293 // for counting tokens.
294 MaxTokens param.Opt[int64] `json:"max_tokens,omitzero"`
295 // How many completions to generate for each prompt.
296 //
297 // **Note:** Because this parameter generates many completions, it can quickly
298 // consume your token quota. Use carefully and ensure that you have reasonable
299 // settings for `max_tokens` and `stop`.
300 N param.Opt[int64] `json:"n,omitzero"`
301 // Number between -2.0 and 2.0. Positive values penalize new tokens based on
302 // whether they appear in the text so far, increasing the model's likelihood to
303 // talk about new topics.
304 //
305 // [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
306 PresencePenalty param.Opt[float64] `json:"presence_penalty,omitzero"`
307 // If specified, our system will make a best effort to sample deterministically,
308 // such that repeated requests with the same `seed` and parameters should return
309 // the same result.
310 //
311 // Determinism is not guaranteed, and you should refer to the `system_fingerprint`
312 // response parameter to monitor changes in the backend.
313 Seed param.Opt[int64] `json:"seed,omitzero"`
314 // The suffix that comes after a completion of inserted text.
315 //
316 // This parameter is only supported for `gpt-3.5-turbo-instruct`.
317 Suffix param.Opt[string] `json:"suffix,omitzero"`
318 // What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
319 // make the output more random, while lower values like 0.2 will make it more
320 // focused and deterministic.
321 //
322 // We generally recommend altering this or `top_p` but not both.
323 Temperature param.Opt[float64] `json:"temperature,omitzero"`
324 // An alternative to sampling with temperature, called nucleus sampling, where the
325 // model considers the results of the tokens with top_p probability mass. So 0.1
326 // means only the tokens comprising the top 10% probability mass are considered.
327 //
328 // We generally recommend altering this or `temperature` but not both.
329 TopP param.Opt[float64] `json:"top_p,omitzero"`
330 // A unique identifier representing your end-user, which can help OpenAI to monitor
331 // and detect abuse.
332 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
333 User param.Opt[string] `json:"user,omitzero"`
334 // Modify the likelihood of specified tokens appearing in the completion.
335 //
336 // Accepts a JSON object that maps tokens (specified by their token ID in the GPT
337 // tokenizer) to an associated bias value from -100 to 100. You can use this
338 // [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs.
339 // Mathematically, the bias is added to the logits generated by the model prior to
340 // sampling. The exact effect will vary per model, but values between -1 and 1
341 // should decrease or increase likelihood of selection; values like -100 or 100
342 // should result in a ban or exclusive selection of the relevant token.
343 //
344 // As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token
345 // from being generated.
346 LogitBias map[string]int64 `json:"logit_bias,omitzero"`
347 // Up to 4 sequences where the API will stop generating further tokens. The
348 // returned text will not contain the stop sequence.
349 Stop CompletionNewParamsStopUnion `json:"stop,omitzero"`
350 // Options for streaming response. Only set this when you set `stream: true`.
351 StreamOptions ChatCompletionStreamOptionsParam `json:"stream_options,omitzero"`
352 paramObj
353}
354
355// IsPresent returns true if the field's value is not omitted and not the JSON
356// "null". To check if this field is omitted, use [param.IsOmitted].
357func (f CompletionNewParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
358
359func (r CompletionNewParams) MarshalJSON() (data []byte, err error) {
360 type shadow CompletionNewParams
361 return param.MarshalObject(r, (*shadow)(&r))
362}
363
364// Only one field can be non-zero.
365//
366// Use [param.IsOmitted] to confirm if a field is set.
367type CompletionNewParamsPromptUnion struct {
368 OfString param.Opt[string] `json:",omitzero,inline"`
369 OfArrayOfStrings []string `json:",omitzero,inline"`
370 OfArrayOfTokens []int64 `json:",omitzero,inline"`
371 OfArrayOfTokenArrays [][]int64 `json:",omitzero,inline"`
372 paramUnion
373}
374
375// IsPresent returns true if the field's value is not omitted and not the JSON
376// "null". To check if this field is omitted, use [param.IsOmitted].
377func (u CompletionNewParamsPromptUnion) IsPresent() bool { return !param.IsOmitted(u) && !u.IsNull() }
378func (u CompletionNewParamsPromptUnion) MarshalJSON() ([]byte, error) {
379 return param.MarshalUnion[CompletionNewParamsPromptUnion](u.OfString, u.OfArrayOfStrings, u.OfArrayOfTokens, u.OfArrayOfTokenArrays)
380}
381
382func (u *CompletionNewParamsPromptUnion) asAny() any {
383 if !param.IsOmitted(u.OfString) {
384 return &u.OfString.Value
385 } else if !param.IsOmitted(u.OfArrayOfStrings) {
386 return &u.OfArrayOfStrings
387 } else if !param.IsOmitted(u.OfArrayOfTokens) {
388 return &u.OfArrayOfTokens
389 } else if !param.IsOmitted(u.OfArrayOfTokenArrays) {
390 return &u.OfArrayOfTokenArrays
391 }
392 return nil
393}
394
395// Only one field can be non-zero.
396//
397// Use [param.IsOmitted] to confirm if a field is set.
398type CompletionNewParamsStopUnion struct {
399 OfString param.Opt[string] `json:",omitzero,inline"`
400 OfCompletionNewsStopArray []string `json:",omitzero,inline"`
401 paramUnion
402}
403
404// IsPresent returns true if the field's value is not omitted and not the JSON
405// "null". To check if this field is omitted, use [param.IsOmitted].
406func (u CompletionNewParamsStopUnion) IsPresent() bool { return !param.IsOmitted(u) && !u.IsNull() }
407func (u CompletionNewParamsStopUnion) MarshalJSON() ([]byte, error) {
408 return param.MarshalUnion[CompletionNewParamsStopUnion](u.OfString, u.OfCompletionNewsStopArray)
409}
410
411func (u *CompletionNewParamsStopUnion) asAny() any {
412 if !param.IsOmitted(u.OfString) {
413 return &u.OfString.Value
414 } else if !param.IsOmitted(u.OfCompletionNewsStopArray) {
415 return &u.OfCompletionNewsStopArray
416 }
417 return nil
418}