Image Generation

Create Image

POST /images/generations

Generate images using the selected provider and model

Creates an image given a prompt.

POSThttps://api.portkey.ai/v1/images/generations

Body

application/json

prompt*string

A text description of the desired image(s). The maximum length is 1000 characters for dall-e-2 and 4000 characters for dall-e-3.

modelnullable any of

The model to use for image generation.

stringenum

nnullable integer

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

qualityenum

The quality of the image that will be generated. hd creates images with finer details and greater consistency across the image. This param is only supported for dall-e-3.

standardhd

response_formatnullable enum

The format in which the generated images are returned. Must be one of url or b64_json.

urlb64_json

sizenullable enum

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.

256x256512x5121024x10241792x10241024x1792

stylenullable enum

The style of the generated images. 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. This param is only supported for dall-e-3.

vividnatural

userstring

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Response

200

OK

Body

application/json

created*integer

data*array of Image (object)

Request

JavaScriptCurl

const response = await fetch('https://api.portkey.ai/v1/images/generations', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "prompt": "A cute baby sea otter"
    }),
});
const data = await response.json();

Response

{
  "data": [
    {
      "b64_json": "text",
      "url": "text",
      "revised_prompt": "text"
    }
  ]
}

Pass the config parameters for the request in the headers as defined here.

Portkey automatically transforms the parameters for image models according the parameters accepted by them.

SDK Usage

The images.create method in the Portkey or OpenAI SDK allows you to generate images using various image models. This method provides a straightforward interface for requesting image generations.

Method Signature

OpenAI NodeJS

client.images.create(requestParams[configParams]);

OpenAI Python

# with only request params
client.images.create(requestParams);

Parameters

1. requestParams (Object): Parameters for the completion request. These parameters should include the prompt and model, and are transformed automatically by Portkey for image models.

2. configParams (Object): Additional configuration options for the request. This is an optional parameter that can include custom config options for this specific request. These will override the configs set in the Portkey Client.

Example Usage

REST API Example

In REST calls, x-portkey-api-key is a compulsory header, it can be paired with the following options for sending provider details:

1. x-portkey-provider & Authorization (or similar auth headers)

2. x-portkey-virtual-key

3. x-portkey-config

Example request using Provider + Auth:

curl "https://api.portkey.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "prompt": "A cute baby sea otter",
    "model": "dall-e-3",
    "n": 1
  }'

Example request using Virtual Key:

curl "https://api.portkey.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -d '{
    "prompt": "A cute baby sea otter",
    "model": "dall-e-3",
    "n": 1
  }'

Example request using Config:

curl "https://api.portkey.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-config: config-key" \
  -d '{
    "prompt": "A cute baby sea otter",
    "model": "dall-e-3",
    "n": 1
  }'

You can send 3 other headers in your Portkey requests

• x-portkey-trace-id: Send trace id

• x-portkey-metadata: Send custom metadata

• x-portkey-cache-force-refresh: Force refresh cache for this request

Example request using these 3:

curl "https://api.portkey.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-config: config-key" \
  -H "x-portkey-trace-id: $UNIQUE_TRACE_ID" \
  -H "x-portkey-metadata: {\"_user\":\"john\"}" \
  -H "x-portkey-cache-force-refresh: True" \
  -d '{
    "prompt": "A cute baby sea otter",
    "model": "dall-e-3",
    "n": 1
  }'

Response Format

The response will conform to the Image Generation Object schema from the Portkey API, typically including the generated image based on the prompt and the selected model.

Reference:

Image generation using OpenAI