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

# Get Image

> An image of your library and how its background removal or expansion went

## Overview

Returns an image of your library with the state of the edits started on it: the image itself (`status` is `PROCESSING` while an expansion paints it) and its background removal (`backgroundRemoval.status`). Poll it after [Remove Image Background](/api-reference/image/remove-background) or [Expand Image](/api-reference/image/expand) until the state you wait for is `COMPLETED`.

## Path Parameters

<ParamField path="mediaId" type="string" required>
  The library image, as returned by the endpoint that started the edit.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.hooked.so/v1/image/media_abc123" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hooked.so/v1/image/media_abc123', {
    headers: { 'x-api-key': 'your_api_key_here' }
  });
  const { data } = await response.json();
  if (data.backgroundRemoval.status === 'COMPLETED') console.log(data.backgroundRemoval.url);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Image details fetched successfully",
    "data": {
      "id": "media_abc123",
      "name": "portrait.jpg",
      "status": "COMPLETED",
      "url": "https://.../portrait.jpg",
      "aspectRatio": null,
      "backgroundRemoval": {
        "status": "COMPLETED",
        "url": "https://.../media_abc123-1726560000000.png"
      },
      "usedCredits": 0.5,
      "createdAt": "2026-09-17T10:00:00.000Z",
      "updatedAt": "2026-09-17T10:00:12.000Z"
    }
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="data.status" type="string">
  `PROCESSING`, `COMPLETED` or `FAILED` — the image itself. Pending while an expansion is being painted.
</ResponseField>

<ResponseField name="data.url" type="string">
  Signed URL of the image; `null` while it is still being made.
</ResponseField>

<ResponseField name="data.backgroundRemoval" type="object">
  `status` is `NONE`, `PROCESSING`, `COMPLETED` or `FAILED`; `url` is the signed PNG with transparency when `COMPLETED`.
</ResponseField>

## Status Codes

| Status       | Code | Description                   |
| ------------ | ---- | ----------------------------- |
| Success      | 200  | Image found                   |
| Unauthorized | 401  | Missing or invalid API key    |
| Not found    | 404  | No such image in your library |


## OpenAPI

````yaml GET /v1/image/{mediaId}
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/{mediaId}:
    get:
      tags:
        - Images
      summary: Get Image
      description: >-
        An image of your library and how its background removal or expansion
        went. Poll it until the state you wait for is COMPLETED.
      operationId: getImageDetails
      parameters:
        - name: mediaId
          in: path
          required: true
          schema:
            type: string
          description: The library image
      responses:
        '200':
          description: Image found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                        enum:
                          - PROCESSING
                          - COMPLETED
                          - FAILED
                      url:
                        type: string
                        nullable: true
                      aspectRatio:
                        type: string
                        nullable: true
                      backgroundRemoval:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - NONE
                              - PROCESSING
                              - COMPLETED
                              - FAILED
                          url:
                            type: string
                            nullable: true
                      usedCredits:
                        type: number
                      createdAt:
                        type: string
                      updatedAt:
                        type: string
              example:
                success: true
                message: Image details fetched successfully
                data:
                  id: media_abc123
                  name: portrait.jpg
                  status: COMPLETED
                  url: https://.../portrait.jpg
                  aspectRatio: null
                  backgroundRemoval:
                    status: COMPLETED
                    url: https://.../media_abc123-1726560000000.png
                  usedCredits: 0.5
                  createdAt: '2026-09-17T10:00:00.000Z'
                  updatedAt: '2026-09-17T10:00:12.000Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: Not authenticated
        '404':
          description: No such image in your library
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: Image not found
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````