cli/resources/images/methods/create_variation/index.md +0 −177 deleted
File Deleted View Diff
1## Create image variation
2
3`$ openai images create-variation`
4
5**post** `/images/variations`
6
7Creates a variation of a given image. This endpoint only supports `dall-e-2`.
8
9### Parameters
10
11- `--image: string`
12
13 The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
14
15- `--model: optional string or ImageModel`
16
17 The model to use for image generation. Only `dall-e-2` is supported at this time.
18
19- `--n: optional number`
20
21 The number of images to generate. Must be between 1 and 10.
22
23- `--response-format: optional "url" or "b64_json"`
24
25 The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated.
26
27- `--size: optional "256x256" or "512x512" or "1024x1024"`
28
29 The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
30
31- `--user: optional string`
32
33 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).
34
35### Returns
36
37- `images_response: object { created, background, data, 4 more }`
38
39 The response from the image generation endpoint.
40
41 - `created: number`
42
43 The Unix timestamp (in seconds) of when the image was created.
44
45 - `background: optional "transparent" or "opaque"`
46
47 The background parameter used for the image generation. Either `transparent` or `opaque`.
48
49 - `"transparent"`
50
51 - `"opaque"`
52
53 - `data: optional array of Image`
54
55 The list of generated images.
56
57 - `b64_json: optional string`
58
59 The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`.
60
61 - `revised_prompt: optional string`
62
63 For `dall-e-3` only, the revised prompt that was used to generate the image.
64
65 - `url: optional string`
66
67 When using `dall-e-2` or `dall-e-3`, the URL of the generated image if `response_format` is set to `url` (default value). Unsupported for the GPT image models.
68
69 - `output_format: optional "png" or "webp" or "jpeg"`
70
71 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
72
73 - `"png"`
74
75 - `"webp"`
76
77 - `"jpeg"`
78
79 - `quality: optional "low" or "medium" or "high"`
80
81 The quality of the image generated. Either `low`, `medium`, or `high`.
82
83 - `"low"`
84
85 - `"medium"`
86
87 - `"high"`
88
89 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`
90
91 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
92
93 - `"1024x1024"`
94
95 - `"1024x1536"`
96
97 - `"1536x1024"`
98
99 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`
100
101 For `gpt-image-1` only, the token usage information for the image generation.
102
103 - `input_tokens: number`
104
105 The number of tokens (images and text) in the input prompt.
106
107 - `input_tokens_details: object { image_tokens, text_tokens }`
108
109 The input tokens detailed information for the image generation.
110
111 - `image_tokens: number`
112
113 The number of image tokens in the input prompt.
114
115 - `text_tokens: number`
116
117 The number of text tokens in the input prompt.
118
119 - `output_tokens: number`
120
121 The number of output tokens generated by the model.
122
123 - `total_tokens: number`
124
125 The total number of tokens (images and text) used for the image generation.
126
127 - `output_tokens_details: optional object { image_tokens, text_tokens }`
128
129 The output token details for the image generation.
130
131 - `image_tokens: number`
132
133 The number of image output tokens generated by the model.
134
135 - `text_tokens: number`
136
137 The number of text output tokens generated by the model.
138
139### Example
140
141```cli
142openai images create-variation \
143 --api-key 'My API Key' \
144 --image 'Example data'
145```
146
147#### Response
148
149```json
150{
151 "created": 0,
152 "background": "transparent",
153 "data": [
154 {
155 "b64_json": "b64_json",
156 "revised_prompt": "revised_prompt",
157 "url": "https://example.com"
158 }
159 ],
160 "output_format": "png",
161 "quality": "low",
162 "size": "1024x1024",
163 "usage": {
164 "input_tokens": 0,
165 "input_tokens_details": {
166 "image_tokens": 0,
167 "text_tokens": 0
168 },
169 "output_tokens": 0,
170 "total_tokens": 0,
171 "output_tokens_details": {
172 "image_tokens": 0,
173 "text_tokens": 0
174 }
175 }
176}
177```