1// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3package openai
4
5import (
6 "bytes"
7 "context"
8 "io"
9 "mime/multipart"
10 "net/http"
11
12 "github.com/openai/openai-go/internal/apiform"
13 "github.com/openai/openai-go/internal/apijson"
14 "github.com/openai/openai-go/internal/requestconfig"
15 "github.com/openai/openai-go/option"
16 "github.com/openai/openai-go/packages/param"
17 "github.com/openai/openai-go/packages/resp"
18)
19
20// ImageService contains methods and other services that help with interacting with
21// the openai API.
22//
23// Note, unlike clients, this service does not read variables from the environment
24// automatically. You should not instantiate this service directly, and instead use
25// the [NewImageService] method instead.
26type ImageService struct {
27 Options []option.RequestOption
28}
29
30// NewImageService generates a new service that applies the given options to each
31// request. These options are applied after the parent client's options (if there
32// is one), and before any request-specific options.
33func NewImageService(opts ...option.RequestOption) (r ImageService) {
34 r = ImageService{}
35 r.Options = opts
36 return
37}
38
39// Creates a variation of a given image.
40func (r *ImageService) NewVariation(ctx context.Context, body ImageNewVariationParams, opts ...option.RequestOption) (res *ImagesResponse, err error) {
41 opts = append(r.Options[:], opts...)
42 path := "images/variations"
43 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
44 return
45}
46
47// Creates an edited or extended image given an original image and a prompt.
48func (r *ImageService) Edit(ctx context.Context, body ImageEditParams, opts ...option.RequestOption) (res *ImagesResponse, err error) {
49 opts = append(r.Options[:], opts...)
50 path := "images/edits"
51 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
52 return
53}
54
55// Creates an image given a prompt.
56func (r *ImageService) Generate(ctx context.Context, body ImageGenerateParams, opts ...option.RequestOption) (res *ImagesResponse, err error) {
57 opts = append(r.Options[:], opts...)
58 path := "images/generations"
59 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
60 return
61}
62
63// Represents the url or the content of an image generated by the OpenAI API.
64type Image struct {
65 // The base64-encoded JSON of the generated image, if `response_format` is
66 // `b64_json`.
67 B64JSON string `json:"b64_json"`
68 // The prompt that was used to generate the image, if there was any revision to the
69 // prompt.
70 RevisedPrompt string `json:"revised_prompt"`
71 // The URL of the generated image, if `response_format` is `url` (default).
72 URL string `json:"url"`
73 // Metadata for the response, check the presence of optional fields with the
74 // [resp.Field.IsPresent] method.
75 JSON struct {
76 B64JSON resp.Field
77 RevisedPrompt resp.Field
78 URL resp.Field
79 ExtraFields map[string]resp.Field
80 raw string
81 } `json:"-"`
82}
83
84// Returns the unmodified JSON received from the API
85func (r Image) RawJSON() string { return r.JSON.raw }
86func (r *Image) UnmarshalJSON(data []byte) error {
87 return apijson.UnmarshalRoot(data, r)
88}
89
90type ImageModel = string
91
92const (
93 ImageModelDallE2 ImageModel = "dall-e-2"
94 ImageModelDallE3 ImageModel = "dall-e-3"
95)
96
97type ImagesResponse struct {
98 Created int64 `json:"created,required"`
99 Data []Image `json:"data,required"`
100 // Metadata for the response, check the presence of optional fields with the
101 // [resp.Field.IsPresent] method.
102 JSON struct {
103 Created resp.Field
104 Data resp.Field
105 ExtraFields map[string]resp.Field
106 raw string
107 } `json:"-"`
108}
109
110// Returns the unmodified JSON received from the API
111func (r ImagesResponse) RawJSON() string { return r.JSON.raw }
112func (r *ImagesResponse) UnmarshalJSON(data []byte) error {
113 return apijson.UnmarshalRoot(data, r)
114}
115
116type ImageNewVariationParams struct {
117 // The image to use as the basis for the variation(s). Must be a valid PNG file,
118 // less than 4MB, and square.
119 Image io.Reader `json:"image,required" format:"binary"`
120 // The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only
121 // `n=1` is supported.
122 N param.Opt[int64] `json:"n,omitzero"`
123 // A unique identifier representing your end-user, which can help OpenAI to monitor
124 // and detect abuse.
125 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
126 User param.Opt[string] `json:"user,omitzero"`
127 // The model to use for image generation. Only `dall-e-2` is supported at this
128 // time.
129 Model ImageModel `json:"model,omitzero"`
130 // The format in which the generated images are returned. Must be one of `url` or
131 // `b64_json`. URLs are only valid for 60 minutes after the image has been
132 // generated.
133 //
134 // Any of "url", "b64_json".
135 ResponseFormat ImageNewVariationParamsResponseFormat `json:"response_format,omitzero"`
136 // The size of the generated images. Must be one of `256x256`, `512x512`, or
137 // `1024x1024`.
138 //
139 // Any of "256x256", "512x512", "1024x1024".
140 Size ImageNewVariationParamsSize `json:"size,omitzero"`
141 paramObj
142}
143
144// IsPresent returns true if the field's value is not omitted and not the JSON
145// "null". To check if this field is omitted, use [param.IsOmitted].
146func (f ImageNewVariationParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
147
148func (r ImageNewVariationParams) MarshalMultipart() (data []byte, contentType string, err error) {
149 buf := bytes.NewBuffer(nil)
150 writer := multipart.NewWriter(buf)
151 err = apiform.MarshalRoot(r, writer)
152 if err != nil {
153 writer.Close()
154 return nil, "", err
155 }
156 err = writer.Close()
157 if err != nil {
158 return nil, "", err
159 }
160 return buf.Bytes(), writer.FormDataContentType(), nil
161}
162
163// The format in which the generated images are returned. Must be one of `url` or
164// `b64_json`. URLs are only valid for 60 minutes after the image has been
165// generated.
166type ImageNewVariationParamsResponseFormat string
167
168const (
169 ImageNewVariationParamsResponseFormatURL ImageNewVariationParamsResponseFormat = "url"
170 ImageNewVariationParamsResponseFormatB64JSON ImageNewVariationParamsResponseFormat = "b64_json"
171)
172
173// The size of the generated images. Must be one of `256x256`, `512x512`, or
174// `1024x1024`.
175type ImageNewVariationParamsSize string
176
177const (
178 ImageNewVariationParamsSize256x256 ImageNewVariationParamsSize = "256x256"
179 ImageNewVariationParamsSize512x512 ImageNewVariationParamsSize = "512x512"
180 ImageNewVariationParamsSize1024x1024 ImageNewVariationParamsSize = "1024x1024"
181)
182
183type ImageEditParams struct {
184 // The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask
185 // is not provided, image must have transparency, which will be used as the mask.
186 Image io.Reader `json:"image,required" format:"binary"`
187 // A text description of the desired image(s). The maximum length is 1000
188 // characters.
189 Prompt string `json:"prompt,required"`
190 // The number of images to generate. Must be between 1 and 10.
191 N param.Opt[int64] `json:"n,omitzero"`
192 // A unique identifier representing your end-user, which can help OpenAI to monitor
193 // and detect abuse.
194 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
195 User param.Opt[string] `json:"user,omitzero"`
196 // The model to use for image generation. Only `dall-e-2` is supported at this
197 // time.
198 Model ImageModel `json:"model,omitzero"`
199 // The format in which the generated images are returned. Must be one of `url` or
200 // `b64_json`. URLs are only valid for 60 minutes after the image has been
201 // generated.
202 //
203 // Any of "url", "b64_json".
204 ResponseFormat ImageEditParamsResponseFormat `json:"response_format,omitzero"`
205 // The size of the generated images. Must be one of `256x256`, `512x512`, or
206 // `1024x1024`.
207 //
208 // Any of "256x256", "512x512", "1024x1024".
209 Size ImageEditParamsSize `json:"size,omitzero"`
210 // An additional image whose fully transparent areas (e.g. where alpha is zero)
211 // indicate where `image` should be edited. Must be a valid PNG file, less than
212 // 4MB, and have the same dimensions as `image`.
213 Mask io.Reader `json:"mask" format:"binary"`
214 paramObj
215}
216
217// IsPresent returns true if the field's value is not omitted and not the JSON
218// "null". To check if this field is omitted, use [param.IsOmitted].
219func (f ImageEditParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
220
221func (r ImageEditParams) MarshalMultipart() (data []byte, contentType string, err error) {
222 buf := bytes.NewBuffer(nil)
223 writer := multipart.NewWriter(buf)
224 err = apiform.MarshalRoot(r, writer)
225 if err != nil {
226 writer.Close()
227 return nil, "", err
228 }
229 err = writer.Close()
230 if err != nil {
231 return nil, "", err
232 }
233 return buf.Bytes(), writer.FormDataContentType(), nil
234}
235
236// The format in which the generated images are returned. Must be one of `url` or
237// `b64_json`. URLs are only valid for 60 minutes after the image has been
238// generated.
239type ImageEditParamsResponseFormat string
240
241const (
242 ImageEditParamsResponseFormatURL ImageEditParamsResponseFormat = "url"
243 ImageEditParamsResponseFormatB64JSON ImageEditParamsResponseFormat = "b64_json"
244)
245
246// The size of the generated images. Must be one of `256x256`, `512x512`, or
247// `1024x1024`.
248type ImageEditParamsSize string
249
250const (
251 ImageEditParamsSize256x256 ImageEditParamsSize = "256x256"
252 ImageEditParamsSize512x512 ImageEditParamsSize = "512x512"
253 ImageEditParamsSize1024x1024 ImageEditParamsSize = "1024x1024"
254)
255
256type ImageGenerateParams struct {
257 // A text description of the desired image(s). The maximum length is 1000
258 // characters for `dall-e-2` and 4000 characters for `dall-e-3`.
259 Prompt string `json:"prompt,required"`
260 // The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only
261 // `n=1` is supported.
262 N param.Opt[int64] `json:"n,omitzero"`
263 // A unique identifier representing your end-user, which can help OpenAI to monitor
264 // and detect abuse.
265 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
266 User param.Opt[string] `json:"user,omitzero"`
267 // The model to use for image generation.
268 Model ImageModel `json:"model,omitzero"`
269 // The format in which the generated images are returned. Must be one of `url` or
270 // `b64_json`. URLs are only valid for 60 minutes after the image has been
271 // generated.
272 //
273 // Any of "url", "b64_json".
274 ResponseFormat ImageGenerateParamsResponseFormat `json:"response_format,omitzero"`
275 // The size of the generated images. Must be one of `256x256`, `512x512`, or
276 // `1024x1024` for `dall-e-2`. Must be one of `1024x1024`, `1792x1024`, or
277 // `1024x1792` for `dall-e-3` models.
278 //
279 // Any of "256x256", "512x512", "1024x1024", "1792x1024", "1024x1792".
280 Size ImageGenerateParamsSize `json:"size,omitzero"`
281 // The style of the generated images. Must be one of `vivid` or `natural`. Vivid
282 // causes the model to lean towards generating hyper-real and dramatic images.
283 // Natural causes the model to produce more natural, less hyper-real looking
284 // images. This param is only supported for `dall-e-3`.
285 //
286 // Any of "vivid", "natural".
287 Style ImageGenerateParamsStyle `json:"style,omitzero"`
288 // The quality of the image that will be generated. `hd` creates images with finer
289 // details and greater consistency across the image. This param is only supported
290 // for `dall-e-3`.
291 //
292 // Any of "standard", "hd".
293 Quality ImageGenerateParamsQuality `json:"quality,omitzero"`
294 paramObj
295}
296
297// IsPresent returns true if the field's value is not omitted and not the JSON
298// "null". To check if this field is omitted, use [param.IsOmitted].
299func (f ImageGenerateParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
300
301func (r ImageGenerateParams) MarshalJSON() (data []byte, err error) {
302 type shadow ImageGenerateParams
303 return param.MarshalObject(r, (*shadow)(&r))
304}
305
306// The quality of the image that will be generated. `hd` creates images with finer
307// details and greater consistency across the image. This param is only supported
308// for `dall-e-3`.
309type ImageGenerateParamsQuality string
310
311const (
312 ImageGenerateParamsQualityStandard ImageGenerateParamsQuality = "standard"
313 ImageGenerateParamsQualityHD ImageGenerateParamsQuality = "hd"
314)
315
316// The format in which the generated images are returned. Must be one of `url` or
317// `b64_json`. URLs are only valid for 60 minutes after the image has been
318// generated.
319type ImageGenerateParamsResponseFormat string
320
321const (
322 ImageGenerateParamsResponseFormatURL ImageGenerateParamsResponseFormat = "url"
323 ImageGenerateParamsResponseFormatB64JSON ImageGenerateParamsResponseFormat = "b64_json"
324)
325
326// The size of the generated images. Must be one of `256x256`, `512x512`, or
327// `1024x1024` for `dall-e-2`. Must be one of `1024x1024`, `1792x1024`, or
328// `1024x1792` for `dall-e-3` models.
329type ImageGenerateParamsSize string
330
331const (
332 ImageGenerateParamsSize256x256 ImageGenerateParamsSize = "256x256"
333 ImageGenerateParamsSize512x512 ImageGenerateParamsSize = "512x512"
334 ImageGenerateParamsSize1024x1024 ImageGenerateParamsSize = "1024x1024"
335 ImageGenerateParamsSize1792x1024 ImageGenerateParamsSize = "1792x1024"
336 ImageGenerateParamsSize1024x1792 ImageGenerateParamsSize = "1024x1792"
337)
338
339// The style of the generated images. Must be one of `vivid` or `natural`. Vivid
340// causes the model to lean towards generating hyper-real and dramatic images.
341// Natural causes the model to produce more natural, less hyper-real looking
342// images. This param is only supported for `dall-e-3`.
343type ImageGenerateParamsStyle string
344
345const (
346 ImageGenerateParamsStyleVivid ImageGenerateParamsStyle = "vivid"
347 ImageGenerateParamsStyleNatural ImageGenerateParamsStyle = "natural"
348)