> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Media abilities: upload and manage WordPress files

> Upload images and files from URLs or base64 payloads, manage attachments, set featured images, and regenerate thumbnails with Maxi AI Core media abilities.

Media abilities let you add files to your WordPress media library, attach them to posts, and manage existing attachments. You can upload from a remote URL or send file content directly as a base64-encoded payload — no FTP access or manual file handling required.

## All media abilities

| Ability                      | Description                                                                                                 | Capability     | Plan |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------- | ---- |
| `maxi/upload-image`          | Upload an image from a URL or base64 payload. Accepts `url` or `filename` + `content_base64`.               | `upload_files` | Lite |
| `maxi/upload-attachment`     | Upload any file type from a URL or base64 payload, with optional title, alt text, caption, and parent post. | `upload_files` | Lite |
| `maxi/get-attachment`        | Get full attachment details including metadata, available sizes, and MIME type.                             | `read`         | Lite |
| `maxi/delete-attachment`     | Permanently delete an attachment and all its generated files.                                               | `delete_posts` | Lite |
| `maxi/list-attachments`      | List attachments with optional filters for MIME type, parent post, or search query.                         | `read`         | Lite |
| `maxi/set-featured-image`    | Set or remove the featured image on a post.                                                                 | `edit_posts`   | Lite |
| `maxi/attach-media`          | Attach a media item to a parent post.                                                                       | `edit_posts`   | Lite |
| `maxi/detach-media`          | Detach a media item, making it unattached in the media library.                                             | `edit_posts`   | Lite |
| `maxi/regenerate-thumbnails` | Regenerate all registered image sizes for an existing attachment.                                           | `upload_files` | Lite |

<Note>
  All upload abilities require the `upload_files` capability. Make sure the WordPress user connected to your AI client has this capability before calling any upload ability.
</Note>

## Key ability examples

### maxi/upload-image

Upload an image to the media library from a remote URL, or send the file content as a base64 string.

<Tabs>
  <Tab title="From URL">
    ```json theme={null}
    {
      "url": "https://example.com/image.jpg",
      "title": "My Image",
      "alt_text": "Description of image"
    }
    ```
  </Tab>

  <Tab title="From base64">
    ```json theme={null}
    {
      "filename": "photo.jpg",
      "content_base64": "BASE64_ENCODED_CONTENT",
      "title": "My Image"
    }
    ```
  </Tab>
</Tabs>

### maxi/upload-attachment

Upload any file type — PDFs, documents, zip archives, and more. Use this when you need to upload something that isn't an image.

```json theme={null}
{
  "url": "https://example.com/document.pdf",
  "title": "Annual Report 2025"
}
```

Like `maxi/upload-image`, you can also pass `filename` + `content_base64` instead of a `url`.

### maxi/set-featured-image

Set the featured image on any post, page, or custom post type by providing the post ID and the attachment ID of an existing media item.

```json theme={null}
{
  "post_id": 123,
  "attachment_id": 456
}
```

To remove the featured image from a post, set `attachment_id` to `null`.

```json theme={null}
{
  "post_id": 123,
  "attachment_id": null
}
```

### maxi/regenerate-thumbnails

Regenerate all registered image sizes for an attachment. Use this after you add new image size registrations to your theme, or after you change an image in the media library.

```json theme={null}
{ "attachment_id": 456 }
```

<Tip>
  If you've uploaded an image and then changed your theme's registered image sizes, run `maxi/regenerate-thumbnails` to create the new sizes for existing uploads. WordPress does not generate missing sizes automatically for previously uploaded files.
</Tip>

## Attaching and detaching media

Use `maxi/attach-media` to associate an existing media item with a parent post, and `maxi/detach-media` to remove that association and return the item to the unattached state. These operations do not delete the file from the media library.

<Warning>
  `maxi/delete-attachment` permanently deletes the attachment record and all generated image files from disk. This action cannot be undone. Use it carefully.
</Warning>