> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokmodel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image generation, editing, and variations

> Generate images from text prompts, edit existing images with a mask, or create variations of an image using TokModel's three image endpoints.

TokModel provides three image endpoints that cover the most common image tasks: generating a new image from a text prompt, editing an existing image using a mask and a prompt, and producing variations of an existing image. All three endpoints return one or more image URLs (or Base64-encoded image data) in a `data` array. Select the tab below for the endpoint you need.

<Tabs>
  <Tab title="Generate">
    ## POST /v1/images/generations

    Generate one or more images from a text description. The model creates the image from scratch based on your prompt.

    ### Request parameters

    <ParamField body="prompt" type="string" required>
      A text description of the image you want to generate. More detailed prompts generally produce better results.
    </ParamField>

    <ParamField body="model" type="string">
      The image generation model to use. Defaults to the provider's standard model if omitted. Use the [list models](/api-reference/models) endpoint for available options.
    </ParamField>

    <ParamField body="n" type="integer" default="1">
      The number of images to generate. Each image is returned as a separate item in the `data` array.
    </ParamField>

    <ParamField body="size" type="string" default="1024x1024">
      The dimensions of the generated images. Supported values depend on the model. Common options include `"256x256"`, `"512x512"`, and `"1024x1024"`.
    </ParamField>

    <ParamField body="response_format" type="string" default="url">
      How to return the generated image. Use `"url"` for a temporary hosted URL or `"b64_json"` for a Base64-encoded string.
    </ParamField>

    ### Example

    ```bash theme={null}
    curl https://tokmodel.com/v1/images/generations \
      --request POST \
      --header "Authorization: Bearer YOUR_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "model": "openai/dall-e-3",
        "prompt": "A photorealistic image of a red panda sitting on a mossy log in a rainforest",
        "n": 1,
        "size": "1024x1024",
        "response_format": "url"
      }'
    ```

    ### Response

    ```json theme={null}
    {
      "created": 1716470400,
      "data": [
        {
          "url": "https://cdn.tokmodel.com/images/generated/abc123.png"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Edit">
    ## POST /v1/images/edits

    Edit an existing image by providing a mask that defines the area to change and a text prompt describing the desired result. Both the image and the mask must be uploaded as PNG files.

    ### Request parameters

    <ParamField body="image" type="file" required>
      The image to edit, uploaded as a PNG file via `multipart/form-data`. Must be square and under 4 MB.
    </ParamField>

    <ParamField body="mask" type="file" required>
      A PNG mask image of the same dimensions as `image`. Transparent areas (alpha = 0) indicate where the model should apply the edit. Opaque areas are left unchanged.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      A text description of the desired edit. Describe what should appear in the masked area.
    </ParamField>

    <ParamField body="model" type="string">
      The model to use for editing.
    </ParamField>

    <ParamField body="n" type="integer" default="1">
      The number of edited images to generate.
    </ParamField>

    <ParamField body="size" type="string" default="1024x1024">
      The size of the output image. Must match the dimensions of the input image.
    </ParamField>

    ### Example

    ```bash theme={null}
    curl https://tokmodel.com/v1/images/edits \
      --request POST \
      --header "Authorization: Bearer YOUR_API_KEY" \
      --form "image=@/path/to/original.png" \
      --form "mask=@/path/to/mask.png" \
      --form "prompt=Replace the background with a sunset over the ocean" \
      --form "model=openai/dall-e-2" \
      --form "n=1" \
      --form "size=1024x1024"
    ```

    ### Response

    ```json theme={null}
    {
      "created": 1716470401,
      "data": [
        {
          "url": "https://cdn.tokmodel.com/images/edits/def456.png"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Variations">
    ## POST /v1/images/variations

    Create one or more variations of an existing image. The model generates new images that are visually similar to the original without requiring a text prompt.

    ### Request parameters

    <ParamField body="image" type="file" required>
      The source image to create variations from, uploaded as a PNG file via `multipart/form-data`. Must be square and under 4 MB.
    </ParamField>

    <ParamField body="model" type="string">
      The model to use for generating variations.
    </ParamField>

    <ParamField body="n" type="integer" default="1">
      The number of image variations to generate.
    </ParamField>

    <ParamField body="size" type="string" default="1024x1024">
      The size of the output images.
    </ParamField>

    ### Example

    ```bash theme={null}
    curl https://tokmodel.com/v1/images/variations \
      --request POST \
      --header "Authorization: Bearer YOUR_API_KEY" \
      --form "image=@/path/to/source.png" \
      --form "model=openai/dall-e-2" \
      --form "n=3" \
      --form "size=512x512"
    ```

    ### Response

    ```json theme={null}
    {
      "created": 1716470402,
      "data": [
        { "url": "https://cdn.tokmodel.com/images/variations/ghi789-1.png" },
        { "url": "https://cdn.tokmodel.com/images/variations/ghi789-2.png" },
        { "url": "https://cdn.tokmodel.com/images/variations/ghi789-3.png" }
      ]
    }
    ```
  </Tab>
</Tabs>