---
title: "Image-to-image"
method: POST
path: "/v1/images/image-to-image"
tags: ["Images"]
---

# Image-to-image

`POST /v1/images/image-to-image`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/images/image-to-image`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/tenstorrent/apis/tt-media-server-api-c-drogon/docs/v1/images/image-to-image/post.ts> (a function with typed inputs; its response is checked against the schema)

Generates a new image from a prompt and an input image. Only registered when the active image runner_type is an image-to-image variant.

## Request body

- ImageGenerateRequest: Superset of fields for /v1/images/generations, /v1/images/image-to-image, and /v1/images/edits. The active route enforces its own subset (image-to-image requires `image`; edits also requires `mask`).
  - `prompt` string, required: Text prompt describing the desired output image
  - `prompt_2` string: Optional secondary prompt routed to the second text encoder (SDXL)
  - `negative_prompt` string: Negative prompt describing what to avoid
  - `negative_prompt_2` string: Optional secondary negative prompt for the second text encoder
  - `num_inference_steps` integer: Number of denoising steps
  - `guidance_scale` number: Classifier-free guidance scale
  - `guidance_rescale` number: Guidance rescale factor (mitigates over-saturation at high guidance)
  - `seed` integer: Random seed for reproducible sampling
  - `number_of_images` integer: Number of images to generate per request
  - `crop_coords_top_left` integer[]: SDXL crop conditioning [top, left]
  - `timesteps` number[]: Optional explicit list of timesteps for the scheduler
  - `sigmas` number[]: Optional explicit list of sigmas for the scheduler
  - `lora_path` string: Path to a LoRA weights file to load before generation
  - `lora_scale` number: Scale applied to the LoRA
  - `image_return_format` 'JPEG' | 'PNG': Encoding format for the returned base64 image bytes
  - `image_quality` integer: Quality factor for JPEG encoding (ignored for PNG). Bounds match the Python service's Pydantic constraint (ge=50, le=100).
  - `image` string: Base64-encoded input image. Required for image-to-image and edits.
  - `mask` string: Base64-encoded mask image. Required for edits/inpainting.
  - `strength` number: Image-to-image strength (0..1); higher values diverge further from the input image.

## Response `200`

Image(s) generated successfully

- ImageResponse
  - `images` string[], required: Generated images, base64-encoded
  - `generation_time` number: Wall-clock generation time in seconds (omitted when zero)

## Other responses

- `400`: Invalid request (missing prompt or image)
- `401`: Missing or invalid authentication token
- `503`: Model not ready

## Changes

- **2026-05-15** `bb6d2b703e7e`: 1 info
  - endpoint added
- **2026-04-03** `d051d35964ca`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/tenstorrent/apis/tt-media-server-api-c-drogon/changes/v1/images/image-to-image/post.md)

---

[API](https://skmtc.dev/tenstorrent/apis/tt-media-server-api-c-drogon.md) - [All operations](https://skmtc.dev/tenstorrent/apis/tt-media-server-api-c-drogon/llms.txt) - [OpenAPI document](https://skmtc.dev/tenstorrent/apis/tt-media-server-api-c-drogon/revisions/f1176db3fd15?raw)