# BeeIMG API — LLM Reference

> This file is written for AI assistants (ChatGPT, Claude, Gemini, Kimi, Grok, MiMo, OpenCode, etc.)
> helping a developer integrate the BeeIMG image hosting API. It is a condensed, machine-readable
> companion to the full human-readable docs at https://beeimg.com/api/

## Base URLs

- Primary: `https://beeimg.com/api/`
- IPv6 (use if Cloudflare returns a 403 on the primary base): `https://ipv6.beeimg.com/api/`

## Endpoints

| Submit | Methods    | Output formats                          | URL                                          |
|--------|------------|------------------------------------------|-----------------------------------------------|
| File   | GET, POST  | text, json, jsonp, xml, redirect          | `//beeimg.com/api/upload/file/{Output}/`      |
| URL    | GET, POST  | text, json, jsonp, xml, redirect          | `//beeimg.com/api/upload/url/{Output}/`       |
| Delete | POST only  | text (`OK` or `ERROR`)                    | `//beeimg.com/delete/{image_id}/`             |

JSON output is recommended — it has the most complete support.

## Request Parameters

| Param        | Where               | Required | Notes                                                                 |
|--------------|---------------------|----------|------------------------------------------------------------------------|
| `image`/`file` | File upload         | Yes      | Send as multipart form file field, GET or POST                        |
| `url`        | URL upload           | Yes      | Remote image URL to fetch and host                                    |
| `apikey`     | Any                  | Optional | Required for album uploads and all delete requests                    |
| `albumid`    | Any                  | Optional | Adds the image to an album; requires `apikey`                         |
| `folder`     | Any                  | Optional | Uploads into a sub-folder inside the album given by `albumid` (see [Albums API](#albums-api)). Pass the 9-char folder ID. |
| `privacy`    | Any                  | Optional | `public` (default), `private` (unlisted), or `truly-private` (Premium)|
| `delete_key` | Delete only          | Yes      | Sent with `apikey` via POST to the delete URL                         |

## Allowed File Types & Size Limits

- **Allowed extensions:** JPG, PNG, GIF, WEBP, AVIF, HEIC, HEIF, ICO, APNG
- **Max file size (Free plan):** 1 MB per image
- **Premium / Super Uploader plans:** higher size limits and higher daily upload counts — exact
  current numbers are on the [Upload Limits FAQ](https://beeimg.com/faq#q7) and the
  [Compare All Plans](https://beeimg.com/premium/compare) page, since these can change over time.
- Files that fail the extension check return error code `2`.
- Files that fail the actual content/format check (e.g. renamed non-image file) return error code `3`.
- Oversized files return error code `4`.

## Albums API

Manage albums and folders programmatically. All requests require authentication via `apikey` or session cookie.

### List Your Albums

```bash
curl -b "uid=...;pass=..." \
     "https://beeimg.com/api/album?mode=list"
```

Returns all albums owned by the authenticated user.

### Create an Album

```bash
curl -X POST \
     -d "action=create_album" \
     -d "title=My Album" \
     -b "uid=...;pass=..." \
     "https://beeimg.com/api/album"
```

Returns the new `album_id` (5 characters).

### Get Album Details & Folders

```bash
# Get album metadata, folders, and images
curl "https://beeimg.com/api/album?id=abc12"

# Get a specific folder (9-char ID) — same endpoint
curl "https://beeimg.com/api/album?id=abcdefghi"
```

The response includes a `folders` array with each folder's `id`, `name`, and image count. Use the folder `id` to upload directly into it.

### Create a Sub-Folder

```bash
curl -X POST \
     -d "action=create_folder" \
     -d "main_album_id=abc12" \
     -d "parent_id=abc12" \
     -d "name=Vacation 2026" \
     -b "uid=...;pass=..." \
     "https://beeimg.com/api/album"
```

Returns the new folder `id` (9 characters). Use `parent_id=abc12` for top-level folders, or a folder ID for nested sub-folders.

### Upload to a Sub-Folder

Use the **same `albumid`** (the 5-char master album ID) and add a `folder` parameter with the 9-char folder ID:

```bash
curl -F file=@photo.jpg \
     -F apikey=aaaa \
     -F albumid=abc12 \
     -F folder=abcdefghi \
     https://beeimg.com/api/upload/file/json/
```

> **Key points:**
> - `albumid` is always the **master album ID** (5 chars), even when uploading to a sub-folder.
> - `folder` is the 9-char folder ID from the `folders` array in the album details response.
> - You can also upload via the upload page with `?albumid=abc12&folder=abcdefghi`.

### Move Images Between Folders

```bash
curl -X POST \
     -d "action=move_image" \
     -d "from_album_id=abcdefghi" \
     -d "to_album_id=abcdef123" \
     -d "image_ids=c4661798442,t5125804229" \
     -b "uid=...;pass=..." \
     "https://beeimg.com/api/album"
```

Moves images from source to target. Accepts `image_ids` as comma-separated BIDB IDs (letter + 10 digits), or a single `image_id`. Images already in the target are skipped. Returns `moved`, `skipped`, and `requested` counts.

### Move Folders

```bash
curl -X POST \
     -d "action=move_folder" \
     -d "new_parent_id=abcdef123" \
     -d "folder_ids=aaaaaaaaa,bbbbbbbbb" \
     -b "uid=...;pass=..." \
     "https://beeimg.com/api/album"
```

Re-parents folders within the same album. Accepts `folder_ids` as comma-separated 9-char IDs, or a single `folder_id`. Prevents moving a folder into itself or its own descendants. Returns `moved`, `unchanged`, and `failed` (with per-folder error details).

### Move All Images in a Folder

```bash
curl -X POST \
     -d "action=move_all_images" \
     -d "from_album_id=abcdefghi" \
     -d "to_album_id=abcdef123" \
     -b "uid=...;pass=..." \
     "https://beeimg.com/api/album"
```

Bulk-moves all images from source to target. Subfolders are not affected. Returns the number of `moved` images.

### Get Folder Tree (for Move UI)

```bash
curl "https://beeimg.com/api/album?id=abc12&mode=tree" \
     -b "uid=...;pass=..."
```

Owner-only. Returns a flat list of all folders in the album (`id`, `name`, `parent_id`) for building a folder-tree picker in move dialogs.

## Album Uploads (via file/URL upload)

To add an uploaded image straight into an album, send the same parameters as a normal file/URL
upload plus:

- `apikey` — your account's API key (required for any album upload)
- `albumid` — the ID of the target album

```bash
curl -F file=@localfile.jpg \
     -F apikey=aaaa \
     -F albumid=zzzz \
     https://beeimg.com/api/upload/file/json/
```

When `albumid` is set, the JSON response includes an `album_url` field (see
[Example JSON Response](#example-json-response-success) below). Without `albumid`, that field is
omitted entirely.

## Example: PHP (cURL) — Upload

```php
$ch = curl_init();
$postData['file'] = new CURLFile('localfile.jpg');
$postData['apikey'] = "aaaa"; // optional
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://beeimg.com/api/upload/file/json/');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
$response = curl_exec($ch);
curl_close($ch);
$jsonResponse = json_decode($response, true);
```

## Example: PHP (cURL) — Delete

```php
$ch = curl_init();
$postData = [
    'delete_key' => 'dddd',
    'apikey' => 'aaaa'
];
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://beeimg.com/delete/a123456789/');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
$response = curl_exec($ch); // "OK" or "ERROR"
curl_close($ch);
```

## Example: Bash cURL

```bash
curl -F file=@localfile.jpg https://beeimg.com/api/upload/file/text/
```

## Example: Node.js (axios + form-data)

```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('file', fs.createReadStream('localfile.jpg'));
// form.append("apikey", "aaaa");
// form.append("albumid", "zzzz");
// form.append("privacy", "public"); // or "private"

const headers = form.getHeaders();

axios.post('https://beeimg.com/api/upload/file/text/', form, {headers})
  .then(response => console.log(response.data))
  .catch(error => console.error(error));
```

## Example JSON Response (Success)

```json
{
  "files": {
    "name": "p2465821538",
    "size": "6251",
    "url": "https://beeimg.com/images/p24658215384.png",
    "thumbnail_url": "https://i.beeimg.com/images/thumb/p24658215384-xs.png",
    "view_url": "https://beeimg.com/view/p2465821538/",
    "album_url": "#",
    "delete_url": "https://beeimg.com/delete/p2465821538/",
    "delete_key": "#",
    "status": "Success",
    "code": "200",
    "storage_used": 23712770,
    "storage_limit": 5368709120,
    "storage_remaining": 5344996350
  }
}
```

Conditional fields to be aware of when parsing the response:

- `album_url` — only present when the upload included an `albumid`. Omitted entirely otherwise.
- `delete_key` — only holds a real, usable deletion key for **anonymous** uploads (no `apikey`
  sent). For uploads made with an `apikey`, it returns the placeholder string `"#"` — delete those
  via the account dashboard, or via `apikey` + `delete_url` instead.

## Example JSON Response (Error)

```json
{
  "files": {
    "status": "Please come back with a URL Thank you :)",
    "code": "0"
  }
}
```

## Error Codes

| Code | Meaning                                                       |
|------|----------------------------------------------------------------|
| 0    | Empty/missing request (no file or URL)                         |
| 1    | Empty file                                                      |
| 2    | File extension not allowed                                     |
| 3    | File type not allowed (detected format)                         |
| 4    | File too large                                                  |
| 5    | Storage error: could not allocate a storage server              |
| 6    | Not a valid image                                               |
| 7    | Database error                                                  |
| 8    | Storage error: could not move the file to storage               |
| 10   | Forbidden host (URL upload)                                     |
| 11   | File upload error (HTTP/PHP)                                    |
| 12   | Cannot fetch the URL (URL upload)                                |
| 13   | Cannot save to temporary folder (URL upload)                     |
| 15   | Uploaded data lost — retry the upload (resumable)                |
| 40   | Storage limit exceeded for your account                          |
| 223  | Maximum upload limit reached                                    |
| 503  | Uploader temporarily disabled                                   |

> Note: error codes might change when BeeIMG migrates to a new backend. Prefer matching on the
> text `status` field over the numeric `code` for long-term integrations.

## Related Pages

- API Key: https://beeimg.com/api/key
- FAQ (upload limits, privacy tiers, deletion policy): https://beeimg.com/faq
- Compare Plans: https://beeimg.com/premium/compare
- Terms of Service: https://beeimg.com/tos

## Changelog

| Date       | Change                                                                                   |
|------------|-------------------------------------------------------------------------------------------|
| 2026-07-29 | Embedded markdown in PHP handler; renamed Ask LLM to Ask AI; fixed dark mode visibility.  |
| 2026-07-29 | Fixed `album_url` in example responses: returns `#` when no album, never `album/0/view/`. |
| 2026-07-29 | Added HEIF and APNG to the allowed extensions list (now centralized in `user_data.php`).   |
| 2026-08-25 | Added move actions (`move_image`, `move_folder`, `move_all_images`) and `mode=tree` to Albums API. |
| 2026-07-29 | Initial version: endpoints, parameters, allowed file types & size limits, error codes, and PHP/cURL/Node examples. |