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

# Generate, edit, and vary images via TokModel's API

> Create new images from text prompts, edit existing images with a mask, or generate stylistic variations using TokModel's image endpoints.

TokModel exposes three image endpoints that follow the OpenAI Images API shape: generate a new image from a text prompt, edit an existing image using a mask, or produce variations of an image. All three endpoints accept a `model` parameter so you can route requests to different image providers without changing your client code.

## Authentication

Include your API key in every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Tabs>
  <Tab title="Generate">
    ## Generate an image from a prompt

    `POST /v1/images/generations` accepts a text `prompt` and returns one or more image URLs. Use the `n` parameter to request multiple images and `size` to control resolution.

    ```bash curl theme={null}
    curl https://tokmodel.com/v1/images/generations \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/dall-e-3",
        "prompt": "A photorealistic white cat sitting on a wooden desk next to a laptop, soft morning light",
        "n": 1,
        "size": "1024x1024"
      }'
    ```

    ### Key parameters

    | Parameter         | Type    | Description                                               |
    | ----------------- | ------- | --------------------------------------------------------- |
    | `model`           | string  | The image model to use, e.g. `openai/dall-e-3`.           |
    | `prompt`          | string  | Text description of the image to generate.                |
    | `n`               | integer | Number of images to return (1–10, model-dependent).       |
    | `size`            | string  | Image dimensions, e.g. `256x256`, `512x512`, `1024x1024`. |
    | `response_format` | string  | `url` (default) or `b64_json`.                            |

    ### Example response

    ```json theme={null}
    {
      "created": 1716489600,
      "data": [
        {
          "url": "https://cdn.tokmodel.com/images/generated/abc123.png",
          "revised_prompt": "A highly detailed photorealistic white cat with bright green eyes sitting on a polished wooden desk beside a silver laptop, bathed in warm soft morning sunlight streaming through a nearby window."
        }
      ]
    }
    ```

    The `url` field contains a temporary link to the generated image. Download and store it if you need it beyond the expiry window.
  </Tab>

  <Tab title="Edit">
    ## Edit an image with a mask

    `POST /v1/images/edits` replaces a region of an existing image based on a prompt. You supply the original image, a mask (a PNG where transparent pixels mark the area to replace), and a text description of what should fill that area.

    The request uses `multipart/form-data` because it includes binary file uploads.

    ```bash curl theme={null}
    curl https://tokmodel.com/v1/images/edits \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "model=openai/dall-e-2" \
      -F "image=@original.png" \
      -F "mask=@mask.png" \
      -F "prompt=A sunlit garden with blooming red roses" \
      -F "n=1" \
      -F "size=1024x1024"
    ```

    ### Key parameters

    | Parameter | Type    | Description                                                  |
    | --------- | ------- | ------------------------------------------------------------ |
    | `model`   | string  | The image model to use, e.g. `openai/dall-e-2`.              |
    | `image`   | file    | The source PNG image to edit (max 4 MB, must be square).     |
    | `mask`    | file    | A PNG mask where transparent areas indicate what to replace. |
    | `prompt`  | string  | Description of what to generate in the masked area.          |
    | `n`       | integer | Number of edited images to return.                           |
    | `size`    | string  | Output dimensions. Must match the source image size.         |

    ### Example response

    ```json theme={null}
    {
      "created": 1716489700,
      "data": [
        {
          "url": "https://cdn.tokmodel.com/images/edited/def456.png"
        }
      ]
    }
    ```

    <Tip>
      Both the source image and the mask must be square PNGs with an alpha channel. Use an image editor or a library like Pillow to ensure the mask is correctly formatted before uploading.
    </Tip>
  </Tab>

  <Tab title="Variations">
    ## Create variations of an image

    `POST /v1/images/variations` generates one or more new images that are stylistically similar to a source image but not identical. No prompt is required — the model derives context directly from the input image.

    The request uses `multipart/form-data`.

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

    ### Key parameters

    | Parameter         | Type    | Description                                              |
    | ----------------- | ------- | -------------------------------------------------------- |
    | `model`           | string  | The image model to use, e.g. `openai/dall-e-2`.          |
    | `image`           | file    | The source PNG image to vary (max 4 MB, must be square). |
    | `n`               | integer | Number of variations to return (1–10).                   |
    | `size`            | string  | Output dimensions: `256x256`, `512x512`, or `1024x1024`. |
    | `response_format` | string  | `url` (default) or `b64_json`.                           |

    ### Example response

    ```json theme={null}
    {
      "created": 1716489800,
      "data": [
        { "url": "https://cdn.tokmodel.com/images/variations/var1.png" },
        { "url": "https://cdn.tokmodel.com/images/variations/var2.png" },
        { "url": "https://cdn.tokmodel.com/images/variations/var3.png" }
      ]
    }
    ```

    Each entry in `data` is an independent variation. All share visual similarity with the source but differ in composition, lighting, or detail.
  </Tab>
</Tabs>