368 lines
9.6 KiB
Markdown
368 lines
9.6 KiB
Markdown
## Create image
|
|
|
|
**post** `/images/generations`
|
|
|
|
Creates an image given a prompt. [Learn more](/docs/guides/images).
|
|
|
|
### Body Parameters
|
|
|
|
- `prompt: string`
|
|
|
|
A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`.
|
|
|
|
- `background: optional "transparent" or "opaque" or "auto"`
|
|
|
|
Allows to set transparency for the background of the generated image(s).
|
|
This parameter is only supported for the GPT image models. Must be one of
|
|
`transparent`, `opaque` or `auto` (default value). When `auto` is used, the
|
|
model will automatically determine the best background for the image.
|
|
|
|
If `transparent`, the output format needs to support transparency, so it
|
|
should be set to either `png` (default value) or `webp`.
|
|
|
|
- `"transparent"`
|
|
|
|
- `"opaque"`
|
|
|
|
- `"auto"`
|
|
|
|
- `model: optional string or ImageModel`
|
|
|
|
The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used.
|
|
|
|
- `string`
|
|
|
|
- `ImageModel = "gpt-image-1.5" or "dall-e-2" or "dall-e-3" or 2 more`
|
|
|
|
- `"gpt-image-1.5"`
|
|
|
|
- `"dall-e-2"`
|
|
|
|
- `"dall-e-3"`
|
|
|
|
- `"gpt-image-1"`
|
|
|
|
- `"gpt-image-1-mini"`
|
|
|
|
- `moderation: optional "low" or "auto"`
|
|
|
|
Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value).
|
|
|
|
- `"low"`
|
|
|
|
- `"auto"`
|
|
|
|
- `n: optional number`
|
|
|
|
The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported.
|
|
|
|
- `output_compression: optional number`
|
|
|
|
The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100.
|
|
|
|
- `output_format: optional "png" or "jpeg" or "webp"`
|
|
|
|
The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`.
|
|
|
|
- `"png"`
|
|
|
|
- `"jpeg"`
|
|
|
|
- `"webp"`
|
|
|
|
- `partial_images: optional number`
|
|
|
|
The number of partial images to generate. This parameter is used for
|
|
streaming responses that return partial images. Value must be between 0 and 3.
|
|
When set to 0, the response will be a single image sent in one streaming event.
|
|
|
|
Note that the final image may be sent before the full number of partial images
|
|
are generated if the full image is generated more quickly.
|
|
|
|
- `quality: optional "standard" or "hd" or "low" or 3 more`
|
|
|
|
The quality of the image that will be generated.
|
|
|
|
- `auto` (default value) will automatically select the best quality for the given model.
|
|
- `high`, `medium` and `low` are supported for the GPT image models.
|
|
- `hd` and `standard` are supported for `dall-e-3`.
|
|
- `standard` is the only option for `dall-e-2`.
|
|
|
|
- `"standard"`
|
|
|
|
- `"hd"`
|
|
|
|
- `"low"`
|
|
|
|
- `"medium"`
|
|
|
|
- `"high"`
|
|
|
|
- `"auto"`
|
|
|
|
- `response_format: optional "url" or "b64_json"`
|
|
|
|
The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images.
|
|
|
|
- `"url"`
|
|
|
|
- `"b64_json"`
|
|
|
|
- `size: optional "auto" or "1024x1024" or "1536x1024" or 5 more`
|
|
|
|
The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for the GPT image models, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`.
|
|
|
|
- `"auto"`
|
|
|
|
- `"1024x1024"`
|
|
|
|
- `"1536x1024"`
|
|
|
|
- `"1024x1536"`
|
|
|
|
- `"256x256"`
|
|
|
|
- `"512x512"`
|
|
|
|
- `"1792x1024"`
|
|
|
|
- `"1024x1792"`
|
|
|
|
- `stream: optional boolean`
|
|
|
|
Generate the image in streaming mode. Defaults to `false`. See the
|
|
[Image generation guide](/docs/guides/image-generation) for more information.
|
|
This parameter is only supported for the GPT image models.
|
|
|
|
- `style: optional "vivid" or "natural"`
|
|
|
|
The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images.
|
|
|
|
- `"vivid"`
|
|
|
|
- `"natural"`
|
|
|
|
- `user: optional string`
|
|
|
|
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).
|
|
|
|
### Returns
|
|
|
|
- `ImagesResponse object { created, background, data, 4 more }`
|
|
|
|
The response from the image generation endpoint.
|
|
|
|
- `created: number`
|
|
|
|
The Unix timestamp (in seconds) of when the image was created.
|
|
|
|
- `background: optional "transparent" or "opaque"`
|
|
|
|
The background parameter used for the image generation. Either `transparent` or `opaque`.
|
|
|
|
- `"transparent"`
|
|
|
|
- `"opaque"`
|
|
|
|
- `data: optional array of Image`
|
|
|
|
The list of generated images.
|
|
|
|
- `b64_json: optional string`
|
|
|
|
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`.
|
|
|
|
- `revised_prompt: optional string`
|
|
|
|
For `dall-e-3` only, the revised prompt that was used to generate the image.
|
|
|
|
- `url: optional string`
|
|
|
|
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.
|
|
|
|
- `output_format: optional "png" or "webp" or "jpeg"`
|
|
|
|
The output format of the image generation. Either `png`, `webp`, or `jpeg`.
|
|
|
|
- `"png"`
|
|
|
|
- `"webp"`
|
|
|
|
- `"jpeg"`
|
|
|
|
- `quality: optional "low" or "medium" or "high"`
|
|
|
|
The quality of the image generated. Either `low`, `medium`, or `high`.
|
|
|
|
- `"low"`
|
|
|
|
- `"medium"`
|
|
|
|
- `"high"`
|
|
|
|
- `size: optional "1024x1024" or "1024x1536" or "1536x1024"`
|
|
|
|
The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
|
|
|
|
- `"1024x1024"`
|
|
|
|
- `"1024x1536"`
|
|
|
|
- `"1536x1024"`
|
|
|
|
- `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`
|
|
|
|
For `gpt-image-1` only, the token usage information for the image generation.
|
|
|
|
- `input_tokens: number`
|
|
|
|
The number of tokens (images and text) in the input prompt.
|
|
|
|
- `input_tokens_details: object { image_tokens, text_tokens }`
|
|
|
|
The input tokens detailed information for the image generation.
|
|
|
|
- `image_tokens: number`
|
|
|
|
The number of image tokens in the input prompt.
|
|
|
|
- `text_tokens: number`
|
|
|
|
The number of text tokens in the input prompt.
|
|
|
|
- `output_tokens: number`
|
|
|
|
The number of output tokens generated by the model.
|
|
|
|
- `total_tokens: number`
|
|
|
|
The total number of tokens (images and text) used for the image generation.
|
|
|
|
- `output_tokens_details: optional object { image_tokens, text_tokens }`
|
|
|
|
The output token details for the image generation.
|
|
|
|
- `image_tokens: number`
|
|
|
|
The number of image output tokens generated by the model.
|
|
|
|
- `text_tokens: number`
|
|
|
|
The number of text output tokens generated by the model.
|
|
|
|
### Example
|
|
|
|
```http
|
|
curl https://api.openai.com/v1/images/generations \
|
|
-H 'Content-Type: application/json' \
|
|
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
|
-d '{
|
|
"prompt": "A cute baby sea otter",
|
|
"background": "transparent",
|
|
"moderation": "low",
|
|
"n": 1,
|
|
"output_compression": 100,
|
|
"output_format": "png",
|
|
"partial_images": 1,
|
|
"quality": "medium",
|
|
"response_format": "url",
|
|
"size": "1024x1024",
|
|
"style": "vivid",
|
|
"user": "user-1234"
|
|
}'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"created": 0,
|
|
"background": "transparent",
|
|
"data": [
|
|
{
|
|
"b64_json": "b64_json",
|
|
"revised_prompt": "revised_prompt",
|
|
"url": "url"
|
|
}
|
|
],
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Generate image
|
|
|
|
```http
|
|
curl https://api.openai.com/v1/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
|
-d '{
|
|
"model": "gpt-image-1.5",
|
|
"prompt": "A cute baby sea otter",
|
|
"n": 1,
|
|
"size": "1024x1024"
|
|
}'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"created": 1713833628,
|
|
"data": [
|
|
{
|
|
"b64_json": "..."
|
|
}
|
|
],
|
|
"usage": {
|
|
"total_tokens": 100,
|
|
"input_tokens": 50,
|
|
"output_tokens": 50,
|
|
"input_tokens_details": {
|
|
"text_tokens": 10,
|
|
"image_tokens": 40
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Streaming
|
|
|
|
```http
|
|
curl https://api.openai.com/v1/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
|
-d '{
|
|
"model": "gpt-image-1.5",
|
|
"prompt": "A cute baby sea otter",
|
|
"n": 1,
|
|
"size": "1024x1024",
|
|
"stream": true
|
|
}' \
|
|
--no-buffer
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
event: image_generation.partial_image
|
|
data: {"type":"image_generation.partial_image","b64_json":"...","partial_image_index":0}
|
|
|
|
event: image_generation.completed
|
|
data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}}
|
|
```
|