---
title: "Expand an image to a new aspect ratio (outpainting)"
method: POST
path: "/v1/images/expand"
tags: ["Images"]
---

# Expand an image to a new aspect ratio (outpainting)

`POST /v1/images/expand`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/expand`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Generates the missing area around an image so it fills a different aspect ratio.

Give the image either as a library file uuid (`file_uuid`) or INLINE as a base64
data URL (`imageData`), not both. `targetAspectRatio` must be one of the ratios
GET /v1/models reports for this tool.

## Request body

- object
  - `file_uuid` string, uuid: Uuid of a library image to expand. Use this or `imageData`.
  - `imageData` string: Base64 data URL of the image to expand. Use this or `file_uuid`.
  - `targetAspectRatio` string, required: Target ratio, e.g. "16:9".
  - `contextPrompt` string: Optional hint describing what should fill the new area.
  - `modelVariant` string: Model variant. Defaults to `standard`.
  - `modelOptions` object: Per-model options; see GET /v1/models.

## Response `200`

The expanded image.

- object
  - `success` boolean
  - `data` object
  - `timestamp` string, date-time

## Other responses

- `400`: Missing image, both file_uuid and imageData, or an aspect ratio this tool does not accept (the message lists the valid ones).
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `403`: file_uuid belongs to another user.
- `404`: file_uuid was not found.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)