openai_types/image/
manual.rs

1// Manual: hand-crafted image types (request/response builders, enums, save helper).
2
3use serde::{Deserialize, Serialize};
4
5/// Image quality level.
6#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
7#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
8#[non_exhaustive]
9pub enum ImageQuality {
10    #[serde(rename = "standard")]
11    Standard,
12    #[serde(rename = "hd")]
13    Hd,
14    #[serde(rename = "low")]
15    Low,
16    #[serde(rename = "medium")]
17    Medium,
18    #[serde(rename = "high")]
19    High,
20    #[serde(rename = "auto")]
21    Auto,
22}
23
24/// Image dimensions.
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
27#[non_exhaustive]
28pub enum ImageSize {
29    #[serde(rename = "auto")]
30    Auto,
31    #[serde(rename = "1024x1024")]
32    S1024x1024,
33    #[serde(rename = "1536x1024")]
34    S1536x1024,
35    #[serde(rename = "1024x1536")]
36    S1024x1536,
37    #[serde(rename = "256x256")]
38    S256x256,
39    #[serde(rename = "512x512")]
40    S512x512,
41    #[serde(rename = "1792x1024")]
42    S1792x1024,
43    #[serde(rename = "1024x1792")]
44    S1024x1792,
45}
46
47/// Image style (dall-e-3 only).
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
50#[non_exhaustive]
51pub enum ImageStyle {
52    #[serde(rename = "vivid")]
53    Vivid,
54    #[serde(rename = "natural")]
55    Natural,
56}
57
58/// Output format for generated images (GPT image models).
59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
60#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
61#[non_exhaustive]
62pub enum ImageOutputFormat {
63    #[serde(rename = "png")]
64    Png,
65    #[serde(rename = "jpeg")]
66    Jpeg,
67    #[serde(rename = "webp")]
68    Webp,
69}
70
71/// Response format for images.
72#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
73#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
74#[non_exhaustive]
75pub enum ImageResponseFormat {
76    #[serde(rename = "url")]
77    Url,
78    #[serde(rename = "b64_json")]
79    B64Json,
80}
81
82/// Background transparency for generated images (GPT image models).
83#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
84#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
85#[non_exhaustive]
86pub enum ImageBackground {
87    #[serde(rename = "transparent")]
88    Transparent,
89    #[serde(rename = "opaque")]
90    Opaque,
91    #[serde(rename = "auto")]
92    Auto,
93}
94
95/// Content moderation level for image generation.
96#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
97#[cfg_attr(feature = "structured", derive(schemars::JsonSchema))]
98#[non_exhaustive]
99pub enum ImageModeration {
100    #[serde(rename = "low")]
101    Low,
102    #[serde(rename = "auto")]
103    Auto,
104}
105
106// -- Request types --
107
108/// Request body for `POST /images/generations`.
109#[derive(Debug, Clone, Serialize)]
110pub struct ImageGenerateRequest {
111    /// Text description of desired image(s).
112    pub prompt: String,
113
114    /// Model to use (e.g. "dall-e-3", "gpt-image-1").
115    #[serde(skip_serializing_if = "Option::is_none")]
116    pub model: Option<String>,
117
118    /// Number of images to generate.
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub n: Option<i64>,
121
122    /// Quality level (standard or hd for dall-e-3; low/medium/high/auto for gpt-image-1).
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub quality: Option<ImageQuality>,
125
126    /// Image dimensions.
127    #[serde(skip_serializing_if = "Option::is_none")]
128    pub size: Option<ImageSize>,
129
130    /// Response format (url or b64_json).
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub response_format: Option<ImageResponseFormat>,
133
134    /// Style (vivid or natural) -- dall-e-3 only.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub style: Option<ImageStyle>,
137
138    /// A unique identifier representing your end-user.
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub user: Option<String>,
141
142    // GPT-image-1 specific fields
143    /// Output format (png, jpeg, webp).
144    #[serde(skip_serializing_if = "Option::is_none")]
145    pub output_format: Option<ImageOutputFormat>,
146
147    /// Output compression quality (0-100).
148    #[serde(skip_serializing_if = "Option::is_none")]
149    pub output_compression: Option<i64>,
150
151    /// Background style (transparent, opaque, auto).
152    #[serde(skip_serializing_if = "Option::is_none")]
153    pub background: Option<ImageBackground>,
154
155    /// Moderation level (low, auto).
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub moderation: Option<ImageModeration>,
158}
159
160impl ImageGenerateRequest {
161    pub fn new(prompt: impl Into<String>) -> Self {
162        Self {
163            prompt: prompt.into(),
164            model: None,
165            n: None,
166            quality: None,
167            size: None,
168            response_format: None,
169            style: None,
170            user: None,
171            output_format: None,
172            output_compression: None,
173            background: None,
174            moderation: None,
175        }
176    }
177
178    pub fn model(mut self, model: impl Into<String>) -> Self {
179        self.model = Some(model.into());
180        self
181    }
182
183    pub fn n(mut self, n: i64) -> Self {
184        self.n = Some(n);
185        self
186    }
187
188    pub fn quality(mut self, quality: ImageQuality) -> Self {
189        self.quality = Some(quality);
190        self
191    }
192
193    pub fn size(mut self, size: ImageSize) -> Self {
194        self.size = Some(size);
195        self
196    }
197
198    pub fn response_format(mut self, response_format: ImageResponseFormat) -> Self {
199        self.response_format = Some(response_format);
200        self
201    }
202
203    pub fn style(mut self, style: ImageStyle) -> Self {
204        self.style = Some(style);
205        self
206    }
207
208    pub fn user(mut self, user: impl Into<String>) -> Self {
209        self.user = Some(user.into());
210        self
211    }
212
213    pub fn output_format(mut self, output_format: ImageOutputFormat) -> Self {
214        self.output_format = Some(output_format);
215        self
216    }
217
218    pub fn output_compression(mut self, output_compression: i64) -> Self {
219        self.output_compression = Some(output_compression);
220        self
221    }
222
223    pub fn background(mut self, background: ImageBackground) -> Self {
224        self.background = Some(background);
225        self
226    }
227
228    pub fn moderation(mut self, moderation: ImageModeration) -> Self {
229        self.moderation = Some(moderation);
230        self
231    }
232}
233
234/// Request body for `POST /images/edits`.
235#[derive(Debug, Clone, Serialize)]
236pub struct ImageEditRequest {
237    /// Image to edit (multipart file).
238    #[serde(skip_serializing)]
239    pub image: Vec<u8>,
240    #[serde(skip_serializing)]
241    pub image_filename: String,
242
243    /// Prompt describing the edit.
244    pub prompt: String,
245
246    /// Additional image for reference (optional).
247    #[serde(skip_serializing)]
248    pub mask: Option<Vec<u8>>,
249    #[serde(skip_serializing)]
250    pub mask_filename: Option<String>,
251
252    /// Model to use.
253    #[serde(skip_serializing_if = "Option::is_none")]
254    pub model: Option<String>,
255
256    /// Number of images to generate.
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub n: Option<i64>,
259
260    /// Image dimensions.
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub size: Option<ImageSize>,
263
264    /// Response format.
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub response_format: Option<ImageResponseFormat>,
267
268    /// A unique identifier representing your end-user.
269    #[serde(skip_serializing_if = "Option::is_none")]
270    pub user: Option<String>,
271}
272
273impl ImageEditRequest {
274    pub fn new(
275        image: Vec<u8>,
276        image_filename: impl Into<String>,
277        prompt: impl Into<String>,
278    ) -> Self {
279        Self {
280            image,
281            image_filename: image_filename.into(),
282            prompt: prompt.into(),
283            mask: None,
284            mask_filename: None,
285            model: None,
286            n: None,
287            size: None,
288            response_format: None,
289            user: None,
290        }
291    }
292}
293
294/// Backward compatibility alias.
295pub type ImageEditParams = ImageEditRequest;
296
297/// Request body for `POST /images/variations`.
298#[derive(Debug, Clone, Serialize)]
299pub struct ImageVariationRequest {
300    /// Image to vary (multipart file).
301    #[serde(skip_serializing)]
302    pub image: Vec<u8>,
303    #[serde(skip_serializing)]
304    pub image_filename: String,
305
306    /// Number of images to generate.
307    #[serde(skip_serializing_if = "Option::is_none")]
308    pub n: Option<i64>,
309
310    /// Image dimensions.
311    #[serde(skip_serializing_if = "Option::is_none")]
312    pub size: Option<ImageSize>,
313
314    /// Response format.
315    #[serde(skip_serializing_if = "Option::is_none")]
316    pub response_format: Option<ImageResponseFormat>,
317
318    /// A unique identifier representing your end-user.
319    #[serde(skip_serializing_if = "Option::is_none")]
320    pub user: Option<String>,
321}
322
323impl ImageVariationRequest {
324    pub fn new(image: Vec<u8>, image_filename: impl Into<String>) -> Self {
325        Self {
326            image,
327            image_filename: image_filename.into(),
328            n: None,
329            size: None,
330            response_format: None,
331            user: None,
332        }
333    }
334}
335
336/// Backward compatibility alias.
337pub type ImageVariationParams = ImageVariationRequest;
338
339// -- Response types --
340
341/// A single generated image.
342#[derive(Debug, Clone, Deserialize)]
343pub struct Image {
344    /// The URL of the generated image (if response_format is url).
345    #[serde(default)]
346    pub url: Option<String>,
347    /// The base64-encoded JSON of the generated image (if response_format is b64_json).
348    #[serde(default)]
349    pub b64_json: Option<String>,
350    /// The prompt that was used to generate the image (dall-e-3 only).
351    #[serde(default)]
352    pub revised_prompt: Option<String>,
353}
354
355/// Response from image generation endpoints.
356#[derive(Debug, Clone, Deserialize)]
357pub struct ImagesResponse {
358    pub created: i64,
359    pub data: Vec<Image>,
360}
openai_types/image/manual.rs

openai_types/image/
manual.rs
