> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Expand Image
> Grow an image to another aspect ratio, with AI painting the new area
## Overview
Starts growing an image to the aspect ratio you ask for. The original is centred on the larger canvas at its own size and the new area is generated, optionally guided by a prompt. The result is a **new** image in your library; the original is not modified. The call answers `202` with the pending image: poll [Get Image](/api-reference/image/details) on that `mediaId` until its `status` is `COMPLETED`.
Accepted formats: JPEG, PNG and WEBP, up to 25 MB. An image that already has the requested ratio is rejected with 400.
## Request Body
ID of an image in your media library. Required unless `imageUrl` is given.
Public URL of the image. It is saved to your library before processing. Required unless `media` is given.
Target ratio: `ratio_9_16`, `ratio_1_1` or `ratio_16_9`.
What the new area should show, in English (up to 500 characters). Without it the scene is continued from the image itself.
```bash cURL theme={null}
curl -X POST "https://api.hooked.so/v1/image/expand" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "media": "media_abc123", "aspectRatio": "ratio_16_9", "prompt": "the same beach, more sand and sky" }'
```
```javascript Node.js theme={null}
const response = await fetch('https://api.hooked.so/v1/image/expand', {
method: 'POST',
headers: { 'x-api-key': 'your_api_key_here', 'Content-Type': 'application/json' },
body: JSON.stringify({ imageUrl: 'https://example.com/product.png', aspectRatio: 'ratio_9_16' })
});
const { data } = await response.json();
console.log(data.mediaId, data.url);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.hooked.so/v1/image/expand',
headers={'x-api-key': 'your_api_key_here'},
json={'media': 'media_abc123', 'aspectRatio': 'ratio_1_1'}
)
print(response.json()['data']['url'])
```
```json 202 Started theme={null}
{
"success": true,
"message": "Image expansion started",
"data": {
"mediaId": "media_def456",
"sourceMediaId": "media_abc123",
"status": "PROCESSING",
"aspectRatio": "ratio_16_9",
"usedCredits": 1
}
}
```
## Response Fields
The new library image being made at the requested ratio. Its `url` arrives in [Get Image](/api-reference/image/details) when `status` is `COMPLETED`.
The image it is grown from.
`PROCESSING` — the expansion is running.
The ratio that was produced.
Credits charged by this call.
## Status Codes
| Status | Code | Description |
| ---------------- | ---- | ---------------------------------------------------------------------- |
| Started | 202 | Expansion running; follow it with Get Image |
| Validation error | 400 | Missing source, bad `aspectRatio`, or the image already has that ratio |
| Unauthorized | 401 | Missing or invalid API key |
| Payment required | 402 | Not enough credits, no active plan, or (BYOK) the Bria key is missing |
| Provider error | 502 | Bria did not take the request; nothing was charged |
If Bria fails later, the pending image ends as `status: "FAILED"` in Get Image and the credits are refunded.
## Related Endpoints
Follow the expansion and read the result
Cut the subject out with a transparent background
Use the image in a video
## OpenAPI
````yaml POST /v1/image/expand
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Images
description: 'Image editing: background removal and expansion'
paths:
/v1/image/expand:
post:
tags:
- Images
summary: Expand Image
description: >-
Start growing an image to another aspect ratio: the original is centred
on the larger canvas at its own size and AI paints the new area. The
result is a new image in your library, answered here as a pending row
(202) to follow through GET /v1/image/{mediaId}; the original is not
modified.
operationId: expandImage
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- aspectRatio
properties:
media:
type: string
description: >-
ID of an image in your media library. Required unless
imageUrl is given.
imageUrl:
type: string
format: uri
description: >-
Public URL of a JPEG, PNG or WEBP image (up to 25 MB).
Imported into your library before processing. Required
unless media is given.
aspectRatio:
type: string
enum:
- ratio_9_16
- ratio_1_1
- ratio_16_9
description: Target aspect ratio
prompt:
type: string
maxLength: 500
description: What the new area should show (English). Optional.
example:
media: media_abc123
aspectRatio: ratio_16_9
prompt: the same beach, more sand and sky
responses:
'202':
description: Expansion started
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
mediaId:
type: string
description: The new library image being made
sourceMediaId:
type: string
status:
type: string
enum:
- PROCESSING
aspectRatio:
type: string
usedCredits:
type: number
example:
success: true
message: Image expansion started
data:
mediaId: media_def456
sourceMediaId: media_abc123
status: PROCESSING
aspectRatio: ratio_16_9
usedCredits: 1
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: 'aspectRatio: Required'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Not authenticated
'402':
description: >-
Payment required: not enough credits, no active plan, or (BYOK) the
Bria key is missing
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
errorCode:
type: string
enum:
- INSUFFICIENT_CREDITS
- SUBSCRIPTION_REQUIRED
- MISSING_CREDENTIALS
message:
type: string
missingProviders:
type: array
items:
type: string
creditsNeeded:
type: number
creditsAvailable:
type: number
example:
success: false
errorCode: INSUFFICIENT_CREDITS
message: Not enough credits to perform this action
creditsNeeded: 0.5
creditsAvailable: 0
'502':
description: Bria did not take the request; nothing was charged
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Bria could not process the image
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````