go/resources/completions/index.md +0 −531 deleted
File Deleted View Diff
1# Completions
2
3## Create completion
4
5`client.Completions.New(ctx, body) (*Completion, error)`
6
7**post** `/completions`
8
9Creates a completion for the provided prompt and parameters.
10
11Returns a completion object, or a sequence of completion objects if the request is streamed.
12
13### Parameters
14
15- `body CompletionNewParams`
16
17 - `Model param.Field[CompletionNewParamsModel]`
18
19 ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them.
20
21 - `string`
22
23 - `CompletionNewParamsModel`
24
25 - `const CompletionNewParamsModelGPT3_5TurboInstruct CompletionNewParamsModel = "gpt-3.5-turbo-instruct"`
26
27 - `const CompletionNewParamsModelDavinci002 CompletionNewParamsModel = "davinci-002"`
28
29 - `const CompletionNewParamsModelBabbage002 CompletionNewParamsModel = "babbage-002"`
30
31 - `Prompt param.Field[CompletionNewParamsPromptUnion]`
32
33 The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
34
35 Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
36
37 - `string`
38
39 - `[]string`
40
41 - `[]int64`
42
43 - `[][]int64`
44
45 - `BestOf param.Field[int64]`
46
47 Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.
48
49 When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.
50
51 **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
52
53 - `Echo param.Field[bool]`
54
55 Echo back the prompt in addition to the completion
56
57 - `FrequencyPenalty param.Field[float64]`
58
59 Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
60
61 [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
62
63 - `LogitBias param.Field[map[string, int64]]`
64
65 Modify the likelihood of specified tokens appearing in the completion.
66
67 Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
68
69 As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated.
70
71 - `Logprobs param.Field[int64]`
72
73 Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.
74
75 The maximum value for `logprobs` is 5.
76
77 - `MaxTokens param.Field[int64]`
78
79 The maximum number of [tokens](/tokenizer) that can be generated in the completion.
80
81 The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
82
83 - `N param.Field[int64]`
84
85 How many completions to generate for each prompt.
86
87 **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
88
89 - `PresencePenalty param.Field[float64]`
90
91 Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
92
93 [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
94
95 - `Seed param.Field[int64]`
96
97 If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.
98
99 Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
100
101 - `Stop param.Field[CompletionNewParamsStopUnion]`
102
103 Not supported with latest reasoning models `o3` and `o4-mini`.
104
105 Up to 4 sequences where the API will stop generating further tokens. The
106 returned text will not contain the stop sequence.
107
108 - `string`
109
110 - `[]string`
111
112 - ``
113
114 - `StreamOptions param.Field[ChatCompletionStreamOptions]`
115
116 Options for streaming response. Only set this when you set `stream: true`.
117
118 - `Suffix param.Field[string]`
119
120 The suffix that comes after a completion of inserted text.
121
122 This parameter is only supported for `gpt-3.5-turbo-instruct`.
123
124 - `Temperature param.Field[float64]`
125
126 What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
127
128 We generally recommend altering this or `top_p` but not both.
129
130 - `TopP param.Field[float64]`
131
132 An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
133
134 We generally recommend altering this or `temperature` but not both.
135
136 - `User param.Field[string]`
137
138 A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
139
140### Returns
141
142- `type Completion struct{…}`
143
144 Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
145
146 - `ID string`
147
148 A unique identifier for the completion.
149
150 - `Choices []CompletionChoice`
151
152 The list of completion choices the model generated for the input prompt.
153
154 - `FinishReason CompletionChoiceFinishReason`
155
156 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
157 `length` if the maximum number of tokens specified in the request was reached,
158 or `content_filter` if content was omitted due to a flag from our content filters.
159
160 - `const CompletionChoiceFinishReasonStop CompletionChoiceFinishReason = "stop"`
161
162 - `const CompletionChoiceFinishReasonLength CompletionChoiceFinishReason = "length"`
163
164 - `const CompletionChoiceFinishReasonContentFilter CompletionChoiceFinishReason = "content_filter"`
165
166 - `Index int64`
167
168 - `Logprobs CompletionChoiceLogprobs`
169
170 - `TextOffset []int64`
171
172 - `TokenLogprobs []float64`
173
174 - `Tokens []string`
175
176 - `TopLogprobs []map[string, float64]`
177
178 - `Text string`
179
180 - `Created int64`
181
182 The Unix timestamp (in seconds) of when the completion was created.
183
184 - `Model string`
185
186 The model used for completion.
187
188 - `Object TextCompletion`
189
190 The object type, which is always "text_completion"
191
192 - `const TextCompletionTextCompletion TextCompletion = "text_completion"`
193
194 - `SystemFingerprint string`
195
196 This fingerprint represents the backend configuration that the model runs with.
197
198 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
199
200 - `Usage CompletionUsage`
201
202 Usage statistics for the completion request.
203
204 - `CompletionTokens int64`
205
206 Number of tokens in the generated completion.
207
208 - `PromptTokens int64`
209
210 Number of tokens in the prompt.
211
212 - `TotalTokens int64`
213
214 Total number of tokens used in the request (prompt + completion).
215
216 - `CompletionTokensDetails CompletionUsageCompletionTokensDetails`
217
218 Breakdown of tokens used in a completion.
219
220 - `AcceptedPredictionTokens int64`
221
222 When using Predicted Outputs, the number of tokens in the
223 prediction that appeared in the completion.
224
225 - `AudioTokens int64`
226
227 Audio input tokens generated by the model.
228
229 - `ReasoningTokens int64`
230
231 Tokens generated by the model for reasoning.
232
233 - `RejectedPredictionTokens int64`
234
235 When using Predicted Outputs, the number of tokens in the
236 prediction that did not appear in the completion. However, like
237 reasoning tokens, these tokens are still counted in the total
238 completion tokens for purposes of billing, output, and context window
239 limits.
240
241 - `PromptTokensDetails CompletionUsagePromptTokensDetails`
242
243 Breakdown of tokens used in the prompt.
244
245 - `AudioTokens int64`
246
247 Audio input tokens present in the prompt.
248
249 - `CachedTokens int64`
250
251 Cached tokens present in the prompt.
252
253### Example
254
255```go
256package main
257
258import (
259 "context"
260 "fmt"
261
262 "github.com/openai/openai-go"
263 "github.com/openai/openai-go/option"
264)
265
266func main() {
267 client := openai.NewClient(
268 option.WithAPIKey("My API Key"),
269 )
270 completion, err := client.Completions.New(context.TODO(), openai.CompletionNewParams{
271 Model: openai.CompletionNewParamsModelGPT3_5TurboInstruct,
272 Prompt: openai.CompletionNewParamsPromptUnion{
273 OfString: openai.String("This is a test."),
274 },
275 })
276 if err != nil {
277 panic(err.Error())
278 }
279 fmt.Printf("%+v\n", completion)
280}
281```
282
283#### Response
284
285```json
286{
287 "id": "id",
288 "choices": [
289 {
290 "finish_reason": "stop",
291 "index": 0,
292 "logprobs": {
293 "text_offset": [
294 0
295 ],
296 "token_logprobs": [
297 0
298 ],
299 "tokens": [
300 "string"
301 ],
302 "top_logprobs": [
303 {
304 "foo": 0
305 }
306 ]
307 },
308 "text": "text"
309 }
310 ],
311 "created": 0,
312 "model": "model",
313 "object": "text_completion",
314 "system_fingerprint": "system_fingerprint",
315 "usage": {
316 "completion_tokens": 0,
317 "prompt_tokens": 0,
318 "total_tokens": 0,
319 "completion_tokens_details": {
320 "accepted_prediction_tokens": 0,
321 "audio_tokens": 0,
322 "reasoning_tokens": 0,
323 "rejected_prediction_tokens": 0
324 },
325 "prompt_tokens_details": {
326 "audio_tokens": 0,
327 "cached_tokens": 0
328 }
329 }
330}
331```
332
333## Domain Types
334
335### Completion
336
337- `type Completion struct{…}`
338
339 Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
340
341 - `ID string`
342
343 A unique identifier for the completion.
344
345 - `Choices []CompletionChoice`
346
347 The list of completion choices the model generated for the input prompt.
348
349 - `FinishReason CompletionChoiceFinishReason`
350
351 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
352 `length` if the maximum number of tokens specified in the request was reached,
353 or `content_filter` if content was omitted due to a flag from our content filters.
354
355 - `const CompletionChoiceFinishReasonStop CompletionChoiceFinishReason = "stop"`
356
357 - `const CompletionChoiceFinishReasonLength CompletionChoiceFinishReason = "length"`
358
359 - `const CompletionChoiceFinishReasonContentFilter CompletionChoiceFinishReason = "content_filter"`
360
361 - `Index int64`
362
363 - `Logprobs CompletionChoiceLogprobs`
364
365 - `TextOffset []int64`
366
367 - `TokenLogprobs []float64`
368
369 - `Tokens []string`
370
371 - `TopLogprobs []map[string, float64]`
372
373 - `Text string`
374
375 - `Created int64`
376
377 The Unix timestamp (in seconds) of when the completion was created.
378
379 - `Model string`
380
381 The model used for completion.
382
383 - `Object TextCompletion`
384
385 The object type, which is always "text_completion"
386
387 - `const TextCompletionTextCompletion TextCompletion = "text_completion"`
388
389 - `SystemFingerprint string`
390
391 This fingerprint represents the backend configuration that the model runs with.
392
393 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
394
395 - `Usage CompletionUsage`
396
397 Usage statistics for the completion request.
398
399 - `CompletionTokens int64`
400
401 Number of tokens in the generated completion.
402
403 - `PromptTokens int64`
404
405 Number of tokens in the prompt.
406
407 - `TotalTokens int64`
408
409 Total number of tokens used in the request (prompt + completion).
410
411 - `CompletionTokensDetails CompletionUsageCompletionTokensDetails`
412
413 Breakdown of tokens used in a completion.
414
415 - `AcceptedPredictionTokens int64`
416
417 When using Predicted Outputs, the number of tokens in the
418 prediction that appeared in the completion.
419
420 - `AudioTokens int64`
421
422 Audio input tokens generated by the model.
423
424 - `ReasoningTokens int64`
425
426 Tokens generated by the model for reasoning.
427
428 - `RejectedPredictionTokens int64`
429
430 When using Predicted Outputs, the number of tokens in the
431 prediction that did not appear in the completion. However, like
432 reasoning tokens, these tokens are still counted in the total
433 completion tokens for purposes of billing, output, and context window
434 limits.
435
436 - `PromptTokensDetails CompletionUsagePromptTokensDetails`
437
438 Breakdown of tokens used in the prompt.
439
440 - `AudioTokens int64`
441
442 Audio input tokens present in the prompt.
443
444 - `CachedTokens int64`
445
446 Cached tokens present in the prompt.
447
448### Completion Choice
449
450- `type CompletionChoice struct{…}`
451
452 - `FinishReason CompletionChoiceFinishReason`
453
454 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
455 `length` if the maximum number of tokens specified in the request was reached,
456 or `content_filter` if content was omitted due to a flag from our content filters.
457
458 - `const CompletionChoiceFinishReasonStop CompletionChoiceFinishReason = "stop"`
459
460 - `const CompletionChoiceFinishReasonLength CompletionChoiceFinishReason = "length"`
461
462 - `const CompletionChoiceFinishReasonContentFilter CompletionChoiceFinishReason = "content_filter"`
463
464 - `Index int64`
465
466 - `Logprobs CompletionChoiceLogprobs`
467
468 - `TextOffset []int64`
469
470 - `TokenLogprobs []float64`
471
472 - `Tokens []string`
473
474 - `TopLogprobs []map[string, float64]`
475
476 - `Text string`
477
478### Completion Usage
479
480- `type CompletionUsage struct{…}`
481
482 Usage statistics for the completion request.
483
484 - `CompletionTokens int64`
485
486 Number of tokens in the generated completion.
487
488 - `PromptTokens int64`
489
490 Number of tokens in the prompt.
491
492 - `TotalTokens int64`
493
494 Total number of tokens used in the request (prompt + completion).
495
496 - `CompletionTokensDetails CompletionUsageCompletionTokensDetails`
497
498 Breakdown of tokens used in a completion.
499
500 - `AcceptedPredictionTokens int64`
501
502 When using Predicted Outputs, the number of tokens in the
503 prediction that appeared in the completion.
504
505 - `AudioTokens int64`
506
507 Audio input tokens generated by the model.
508
509 - `ReasoningTokens int64`
510
511 Tokens generated by the model for reasoning.
512
513 - `RejectedPredictionTokens int64`
514
515 When using Predicted Outputs, the number of tokens in the
516 prediction that did not appear in the completion. However, like
517 reasoning tokens, these tokens are still counted in the total
518 completion tokens for purposes of billing, output, and context window
519 limits.
520
521 - `PromptTokensDetails CompletionUsagePromptTokensDetails`
522
523 Breakdown of tokens used in the prompt.
524
525 - `AudioTokens int64`
526
527 Audio input tokens present in the prompt.
528
529 - `CachedTokens int64`
530
531 Cached tokens present in the prompt.