TokenLab

Images

Create Image Variation

Creates a variation of a given image

POST
/v1/images/variations

Overview

This endpoint supports existing OpenAI Variations clients. For new image-to-image features, use /v1/images/edits or /v1/images/generations with a current image-to-image model. Requests use multipart/form-data.

Request Body

This endpoint is synchronous: the response carries the final image and never a task. Set your HTTP client timeout to at least 120s.

imagefilerequired

Multipart source image. The file and complete request body must each fit within 50 MiB (larger uploads return 413). Supported formats and dimensions depend on the selected model. Only a model whose details map image-to-image to /v1/images/variations is accepted; any other model returns 400.

modelstringrequired

Model ID. This endpoint has no default model. The examples use the placeholder your-legacy-variation-model: replace it with a model whose details list this endpoint.

nintegerdefault: 1

Number of images to generate (1-10, model dependent).

sizestring

Generated image size. Supported values depend on the selected model.

response_formatstring

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

userstring

A unique identifier representing your end-user for abuse monitoring.

Response

createdinteger

Unix timestamp of when the images were created.

dataarray

Array of generated image variations.

Each object contains:

  • url (string): URL of the variation image (if response_format is url)
  • b64_json (string): Base64-encoded image (if response_format is b64_json)

Request

curl -X POST "https://api.tokenlab.sh/v1/images/variations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=your-legacy-variation-model" \
  -F "image=@cat.png" \
  -F "n=2" \
  -F "size=1024x1024"

Response

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}

Notes

This is a legacy compatibility endpoint. It is not included in the current recommended image model catalog. For new integrations, use /v1/images/edits with gpt-image-2, or /v1/images/generations with operation: "image-to-image" and a current image-to-image model.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"

Request Body

multipart/form-data

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json