java/resources/completions/index.md +0 −520 deleted
File Deleted View Diff
1# Completions
2
3## Create completion
4
5`Completion completions().create(CompletionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`
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- `CompletionCreateParams params`
16
17 - `Model model`
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 - `GPT_3_5_TURBO_INSTRUCT("gpt-3.5-turbo-instruct")`
22
23 - `DAVINCI_002("davinci-002")`
24
25 - `BABBAGE_002("babbage-002")`
26
27 - `Optional<Prompt> prompt`
28
29 The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
30
31 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.
32
33 - `String`
34
35 - `List<String>`
36
37 - `List<long>`
38
39 - `List<List<long>>`
40
41 - `Optional<Long> bestOf`
42
43 Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.
44
45 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`.
46
47 **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`.
48
49 - `Optional<Boolean> echo`
50
51 Echo back the prompt in addition to the completion
52
53 - `Optional<Double> frequencyPenalty`
54
55 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.
56
57 [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
58
59 - `Optional<LogitBias> logitBias`
60
61 Modify the likelihood of specified tokens appearing in the completion.
62
63 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.
64
65 As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated.
66
67 - `Optional<Long> logprobs`
68
69 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.
70
71 The maximum value for `logprobs` is 5.
72
73 - `Optional<Long> maxTokens`
74
75 The maximum number of [tokens](/tokenizer) that can be generated in the completion.
76
77 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.
78
79 - `Optional<Long> n`
80
81 How many completions to generate for each prompt.
82
83 **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`.
84
85 - `Optional<Double> presencePenalty`
86
87 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.
88
89 [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation)
90
91 - `Optional<Long> seed`
92
93 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.
94
95 Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
96
97 - `Optional<Stop> stop`
98
99 Not supported with latest reasoning models `o3` and `o4-mini`.
100
101 Up to 4 sequences where the API will stop generating further tokens. The
102 returned text will not contain the stop sequence.
103
104 - `String`
105
106 - `List<String>`
107
108 - `Optional<ChatCompletionStreamOptions> streamOptions`
109
110 Options for streaming response. Only set this when you set `stream: true`.
111
112 - `Optional<String> suffix`
113
114 The suffix that comes after a completion of inserted text.
115
116 This parameter is only supported for `gpt-3.5-turbo-instruct`.
117
118 - `Optional<Double> temperature`
119
120 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.
121
122 We generally recommend altering this or `top_p` but not both.
123
124 - `Optional<Double> topP`
125
126 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.
127
128 We generally recommend altering this or `temperature` but not both.
129
130 - `Optional<String> user`
131
132 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).
133
134### Returns
135
136- `class Completion:`
137
138 Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
139
140 - `String id`
141
142 A unique identifier for the completion.
143
144 - `List<CompletionChoice> choices`
145
146 The list of completion choices the model generated for the input prompt.
147
148 - `FinishReason finishReason`
149
150 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
151 `length` if the maximum number of tokens specified in the request was reached,
152 or `content_filter` if content was omitted due to a flag from our content filters.
153
154 - `STOP("stop")`
155
156 - `LENGTH("length")`
157
158 - `CONTENT_FILTER("content_filter")`
159
160 - `long index`
161
162 - `Optional<Logprobs> logprobs`
163
164 - `Optional<List<Long>> textOffset`
165
166 - `Optional<List<Double>> tokenLogprobs`
167
168 - `Optional<List<String>> tokens`
169
170 - `Optional<List<TopLogprob>> topLogprobs`
171
172 - `String text`
173
174 - `long created`
175
176 The Unix timestamp (in seconds) of when the completion was created.
177
178 - `String model`
179
180 The model used for completion.
181
182 - `JsonValue; object_ "text_completion"constant`
183
184 The object type, which is always "text_completion"
185
186 - `TEXT_COMPLETION("text_completion")`
187
188 - `Optional<String> systemFingerprint`
189
190 This fingerprint represents the backend configuration that the model runs with.
191
192 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
193
194 - `Optional<CompletionUsage> usage`
195
196 Usage statistics for the completion request.
197
198 - `long completionTokens`
199
200 Number of tokens in the generated completion.
201
202 - `long promptTokens`
203
204 Number of tokens in the prompt.
205
206 - `long totalTokens`
207
208 Total number of tokens used in the request (prompt + completion).
209
210 - `Optional<CompletionTokensDetails> completionTokensDetails`
211
212 Breakdown of tokens used in a completion.
213
214 - `Optional<Long> acceptedPredictionTokens`
215
216 When using Predicted Outputs, the number of tokens in the
217 prediction that appeared in the completion.
218
219 - `Optional<Long> audioTokens`
220
221 Audio input tokens generated by the model.
222
223 - `Optional<Long> reasoningTokens`
224
225 Tokens generated by the model for reasoning.
226
227 - `Optional<Long> rejectedPredictionTokens`
228
229 When using Predicted Outputs, the number of tokens in the
230 prediction that did not appear in the completion. However, like
231 reasoning tokens, these tokens are still counted in the total
232 completion tokens for purposes of billing, output, and context window
233 limits.
234
235 - `Optional<PromptTokensDetails> promptTokensDetails`
236
237 Breakdown of tokens used in the prompt.
238
239 - `Optional<Long> audioTokens`
240
241 Audio input tokens present in the prompt.
242
243 - `Optional<Long> cachedTokens`
244
245 Cached tokens present in the prompt.
246
247### Example
248
249```java
250package com.openai.example;
251
252import com.openai.client.OpenAIClient;
253import com.openai.client.okhttp.OpenAIOkHttpClient;
254import com.openai.models.completions.Completion;
255import com.openai.models.completions.CompletionCreateParams;
256
257public final class Main {
258 private Main() {}
259
260 public static void main(String[] args) {
261 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
262
263 CompletionCreateParams params = CompletionCreateParams.builder()
264 .model(CompletionCreateParams.Model.GPT_3_5_TURBO_INSTRUCT)
265 .prompt("This is a test.")
266 .build();
267 Completion completion = client.completions().create(params);
268 }
269}
270```
271
272#### Response
273
274```json
275{
276 "id": "id",
277 "choices": [
278 {
279 "finish_reason": "stop",
280 "index": 0,
281 "logprobs": {
282 "text_offset": [
283 0
284 ],
285 "token_logprobs": [
286 0
287 ],
288 "tokens": [
289 "string"
290 ],
291 "top_logprobs": [
292 {
293 "foo": 0
294 }
295 ]
296 },
297 "text": "text"
298 }
299 ],
300 "created": 0,
301 "model": "model",
302 "object": "text_completion",
303 "system_fingerprint": "system_fingerprint",
304 "usage": {
305 "completion_tokens": 0,
306 "prompt_tokens": 0,
307 "total_tokens": 0,
308 "completion_tokens_details": {
309 "accepted_prediction_tokens": 0,
310 "audio_tokens": 0,
311 "reasoning_tokens": 0,
312 "rejected_prediction_tokens": 0
313 },
314 "prompt_tokens_details": {
315 "audio_tokens": 0,
316 "cached_tokens": 0
317 }
318 }
319}
320```
321
322## Domain Types
323
324### Completion
325
326- `class Completion:`
327
328 Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
329
330 - `String id`
331
332 A unique identifier for the completion.
333
334 - `List<CompletionChoice> choices`
335
336 The list of completion choices the model generated for the input prompt.
337
338 - `FinishReason finishReason`
339
340 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
341 `length` if the maximum number of tokens specified in the request was reached,
342 or `content_filter` if content was omitted due to a flag from our content filters.
343
344 - `STOP("stop")`
345
346 - `LENGTH("length")`
347
348 - `CONTENT_FILTER("content_filter")`
349
350 - `long index`
351
352 - `Optional<Logprobs> logprobs`
353
354 - `Optional<List<Long>> textOffset`
355
356 - `Optional<List<Double>> tokenLogprobs`
357
358 - `Optional<List<String>> tokens`
359
360 - `Optional<List<TopLogprob>> topLogprobs`
361
362 - `String text`
363
364 - `long created`
365
366 The Unix timestamp (in seconds) of when the completion was created.
367
368 - `String model`
369
370 The model used for completion.
371
372 - `JsonValue; object_ "text_completion"constant`
373
374 The object type, which is always "text_completion"
375
376 - `TEXT_COMPLETION("text_completion")`
377
378 - `Optional<String> systemFingerprint`
379
380 This fingerprint represents the backend configuration that the model runs with.
381
382 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
383
384 - `Optional<CompletionUsage> usage`
385
386 Usage statistics for the completion request.
387
388 - `long completionTokens`
389
390 Number of tokens in the generated completion.
391
392 - `long promptTokens`
393
394 Number of tokens in the prompt.
395
396 - `long totalTokens`
397
398 Total number of tokens used in the request (prompt + completion).
399
400 - `Optional<CompletionTokensDetails> completionTokensDetails`
401
402 Breakdown of tokens used in a completion.
403
404 - `Optional<Long> acceptedPredictionTokens`
405
406 When using Predicted Outputs, the number of tokens in the
407 prediction that appeared in the completion.
408
409 - `Optional<Long> audioTokens`
410
411 Audio input tokens generated by the model.
412
413 - `Optional<Long> reasoningTokens`
414
415 Tokens generated by the model for reasoning.
416
417 - `Optional<Long> rejectedPredictionTokens`
418
419 When using Predicted Outputs, the number of tokens in the
420 prediction that did not appear in the completion. However, like
421 reasoning tokens, these tokens are still counted in the total
422 completion tokens for purposes of billing, output, and context window
423 limits.
424
425 - `Optional<PromptTokensDetails> promptTokensDetails`
426
427 Breakdown of tokens used in the prompt.
428
429 - `Optional<Long> audioTokens`
430
431 Audio input tokens present in the prompt.
432
433 - `Optional<Long> cachedTokens`
434
435 Cached tokens present in the prompt.
436
437### Completion Choice
438
439- `class CompletionChoice:`
440
441 - `FinishReason finishReason`
442
443 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
444 `length` if the maximum number of tokens specified in the request was reached,
445 or `content_filter` if content was omitted due to a flag from our content filters.
446
447 - `STOP("stop")`
448
449 - `LENGTH("length")`
450
451 - `CONTENT_FILTER("content_filter")`
452
453 - `long index`
454
455 - `Optional<Logprobs> logprobs`
456
457 - `Optional<List<Long>> textOffset`
458
459 - `Optional<List<Double>> tokenLogprobs`
460
461 - `Optional<List<String>> tokens`
462
463 - `Optional<List<TopLogprob>> topLogprobs`
464
465 - `String text`
466
467### Completion Usage
468
469- `class CompletionUsage:`
470
471 Usage statistics for the completion request.
472
473 - `long completionTokens`
474
475 Number of tokens in the generated completion.
476
477 - `long promptTokens`
478
479 Number of tokens in the prompt.
480
481 - `long totalTokens`
482
483 Total number of tokens used in the request (prompt + completion).
484
485 - `Optional<CompletionTokensDetails> completionTokensDetails`
486
487 Breakdown of tokens used in a completion.
488
489 - `Optional<Long> acceptedPredictionTokens`
490
491 When using Predicted Outputs, the number of tokens in the
492 prediction that appeared in the completion.
493
494 - `Optional<Long> audioTokens`
495
496 Audio input tokens generated by the model.
497
498 - `Optional<Long> reasoningTokens`
499
500 Tokens generated by the model for reasoning.
501
502 - `Optional<Long> rejectedPredictionTokens`
503
504 When using Predicted Outputs, the number of tokens in the
505 prediction that did not appear in the completion. However, like
506 reasoning tokens, these tokens are still counted in the total
507 completion tokens for purposes of billing, output, and context window
508 limits.
509
510 - `Optional<PromptTokensDetails> promptTokensDetails`
511
512 Breakdown of tokens used in the prompt.
513
514 - `Optional<Long> audioTokens`
515
516 Audio input tokens present in the prompt.
517
518 - `Optional<Long> cachedTokens`
519
520 Cached tokens present in the prompt.