java/resources/images/methods/create_variation/index.md

Create image variation

ImagesResponse images().createVariation(ImageCreateVariationParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /images/variations

Creates a variation of a given image. This endpoint only supports dall-e-2.

Parameters

ImageCreateVariationParams params
- String image
  
  The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
- Optional<ImageModel> model
  
  The model to use for image generation. Only dall-e-2 is supported at this time.
- Optional<Long> n
  
  The number of images to generate. Must be between 1 and 10.
- Optional<ResponseFormat> responseFormat
  
  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.
  - URL("url")
  - B64_JSON("b64_json")
- Optional<Size> size
  
  The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
  - _256X256("256x256")
  - _512X512("512x512")
  - _1024X1024("1024x1024")
- Optional<String> user
  
  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

class ImagesResponse:

The response from the image generation endpoint.
- long created
  
  The Unix timestamp (in seconds) of when the image was created.
- Optional<Background> background
  
  The background parameter used for the image generation. Either transparent or opaque.
  - TRANSPARENT("transparent")
  - OPAQUE("opaque")
- Optional<List<Image>> data
  
  The list of generated images.
  - Optional<String> b64Json
    
    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.
  - Optional<String> revisedPrompt
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - Optional<String> url
    
    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.
- Optional<OutputFormat> outputFormat
  
  The output format of the image generation. Either png, webp, or jpeg.
  - PNG("png")
  - WEBP("webp")
  - JPEG("jpeg")
- Optional<Quality> quality
  
  The quality of the image generated. Either low, medium, or high.
  - LOW("low")
  - MEDIUM("medium")
  - HIGH("high")
- Optional<Size> size
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - _1024X1024("1024x1024")
  - _1024X1536("1024x1536")
  - _1536X1024("1536x1024")
- Optional<Usage> usage
  
  For gpt-image-1 only, the token usage information for the image generation.
  - long inputTokens
    
    The number of tokens (images and text) in the input prompt.
  - InputTokensDetails inputTokensDetails
    
    The input tokens detailed information for the image generation.
    - long imageTokens
      
      The number of image tokens in the input prompt.
    - long textTokens
      
      The number of text tokens in the input prompt.
  - long outputTokens
    
    The number of output tokens generated by the model.
  - long totalTokens
    
    The total number of tokens (images and text) used for the image generation.
  - Optional<OutputTokensDetails> outputTokensDetails
    
    The output token details for the image generation.
    - long imageTokens
      
      The number of image output tokens generated by the model.
    - long textTokens
      
      The number of text output tokens generated by the model.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.images.ImageCreateVariationParams;
import com.openai.models.images.ImagesResponse;
import java.io.ByteArrayInputStream;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ImageCreateVariationParams params = ImageCreateVariationParams.builder()
            .image(new ByteArrayInputStream("Example data".getBytes()))
            .build();
        ImagesResponse imagesResponse = client.images().createVariation(params);
    }
}

Response

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

java/resources/images/methods/create_variation/index.md +206 −0 created

1## Create image variation

3`ImagesResponse images().createVariation(ImageCreateVariationParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

5**post** `/images/variations`

7Creates a variation of a given image. This endpoint only supports `dall-e-2`.

9### Parameters

11- `ImageCreateVariationParams params`

13 - `String image`

15 The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.

17 - `Optional<ImageModel> model`

19 The model to use for image generation. Only `dall-e-2` is supported at this time.

21 - `Optional<Long> n`

23 The number of images to generate. Must be between 1 and 10.

25 - `Optional<ResponseFormat> responseFormat`

27 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.

29 - `URL("url")`

31 - `B64_JSON("b64_json")`

33 - `Optional<Size> size`

35 The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.

37 - `_256X256("256x256")`

39 - `_512X512("512x512")`

41 - `_1024X1024("1024x1024")`

43 - `Optional<String> user`

45 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).

47### Returns

49- `class ImagesResponse:`

51 The response from the image generation endpoint.

53 - `long created`

55 The Unix timestamp (in seconds) of when the image was created.

57 - `Optional<Background> background`

59 The background parameter used for the image generation. Either `transparent` or `opaque`.

61 - `TRANSPARENT("transparent")`

63 - `OPAQUE("opaque")`

65 - `Optional<List<Image>> data`

67 The list of generated images.

69 - `Optional<String> b64Json`

71 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`.

73 - `Optional<String> revisedPrompt`

75 For `dall-e-3` only, the revised prompt that was used to generate the image.

77 - `Optional<String> url`

79 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.

81 - `Optional<OutputFormat> outputFormat`

83 The output format of the image generation. Either `png`, `webp`, or `jpeg`.

85 - `PNG("png")`

87 - `WEBP("webp")`

89 - `JPEG("jpeg")`

91 - `Optional<Quality> quality`

93 The quality of the image generated. Either `low`, `medium`, or `high`.

95 - `LOW("low")`

97 - `MEDIUM("medium")`

99 - `HIGH("high")`

100

101 - `Optional<Size> size`

102

103 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.

104

105 - `_1024X1024("1024x1024")`

106

107 - `_1024X1536("1024x1536")`

108

109 - `_1536X1024("1536x1024")`

110

111 - `Optional<Usage> usage`

112

113 For `gpt-image-1` only, the token usage information for the image generation.

114

115 - `long inputTokens`

116

117 The number of tokens (images and text) in the input prompt.

118

119 - `InputTokensDetails inputTokensDetails`

120

121 The input tokens detailed information for the image generation.

122

123 - `long imageTokens`

124

125 The number of image tokens in the input prompt.

126

127 - `long textTokens`

128

129 The number of text tokens in the input prompt.

130

131 - `long outputTokens`

132

133 The number of output tokens generated by the model.

134

135 - `long totalTokens`

136

137 The total number of tokens (images and text) used for the image generation.

138

139 - `Optional<OutputTokensDetails> outputTokensDetails`

140

141 The output token details for the image generation.

142

143 - `long imageTokens`

144

145 The number of image output tokens generated by the model.

146

147 - `long textTokens`

148

149 The number of text output tokens generated by the model.

150

151### Example

152

153```java

154package com.openai.example;

155

156import com.openai.client.OpenAIClient;

157import com.openai.client.okhttp.OpenAIOkHttpClient;

158import com.openai.models.images.ImageCreateVariationParams;

159import com.openai.models.images.ImagesResponse;

160import java.io.ByteArrayInputStream;

161

162public final class Main {

163 private Main() {}

164

165 public static void main(String[] args) {

166 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

167

168 ImageCreateVariationParams params = ImageCreateVariationParams.builder()

169 .image(new ByteArrayInputStream("Example data".getBytes()))

170 .build();

171 ImagesResponse imagesResponse = client.images().createVariation(params);

172 }

173}

174```

175

176#### Response

177

178```json

179{

180 "created": 0,

181 "background": "transparent",

182 "data": [

183 {

184 "b64_json": "b64_json",

185 "revised_prompt": "revised_prompt",

186 "url": "https://example.com"

187 }

188 ],

189 "output_format": "png",

190 "quality": "low",

191 "size": "1024x1024",

192 "usage": {

193 "input_tokens": 0,

194 "input_tokens_details": {

195 "image_tokens": 0,

196 "text_tokens": 0

197 },

198 "output_tokens": 0,

199 "total_tokens": 0,

200 "output_tokens_details": {

201 "image_tokens": 0,

202 "text_tokens": 0

203 }

204 }

205}

206```