# ACG Random Image API

Base URL: https://acg.284164.xyz
Authentication: none
Methods: GET or HEAD only
CORS: Access-Control-Allow-Origin: *

Purpose: random anime-image retrieval and image-list access. This document is written for AI agents and programs.

## Endpoints

### GET /api.php
Choose portrait or landscape by request User-Agent.
Response: HTTP 302. Mobile User-Agent redirects to /pe.php; other User-Agents redirect to /pc.php. Query parameters are preserved.

### GET /pc.php
Random landscape image.

### GET /pe.php
Random portrait image.

### GET /random.php
Random image without orientation filtering.

The three image-pool endpoints support the same optional query parameter:

- no `return` parameter: HTTP 302 with `Location` pointing to the selected image.
- `return=json`: HTTP 200 application/json.
- `return=all`: HTTP 200 text/plain containing one absolute image URL per line.
- `return=redirect`: same behavior as no parameter.
- any other non-empty value: HTTP 400 application/json.

Example JSON response:
{"code":"200","acgurl":"https://acg.284164.xyz/images/0123456789abcdef01234567.jpg","width":"1920","height":"1080","size":"jpg"}

JSON field meanings:
- code: string status code; "200" on success.
- acgurl: absolute immutable image URL.
- width: image width as a decimal string.
- height: image height as a decimal string.
- size: one of jpg, png, webp.

### GET /gallery.json
HTTP 200 application/json. Returns the complete image manifest as an array.
Each item has:
- file: hash-based filename relative to /images/.
- width: integer pixel width.
- height: integer pixel height.
- size: jpg, png, or webp.
- orientation: pc for landscape/square, pe for portrait.

Construct a public image URL as:
https://acg.284164.xyz/images/{file}

### GET /stats.json
HTTP 200 application/json.
Response fields:
- code: "200"
- total: all images
- landscape: landscape/square images
- portrait: portrait images

### GET /test.php
### GET /healthz
HTTP 200 text/plain with body: Hello World

### GET /images/{file}
Returns an image/jpeg, image/png, or image/webp asset.
Valid filenames are 24 lowercase hexadecimal characters plus .jpg, .png, or .webp.
Assets are immutable and cacheable for one year.

### GET /openapi.json
Machine-readable OpenAPI 3.1 description.

## Examples

Random image URL via JSON:
curl -sS 'https://acg.284164.xyz/random.php?return=json'

Follow redirect and download a landscape image:
curl -L 'https://acg.284164.xyz/pc.php' -o image.jpg

Get all portrait image URLs:
curl -sS 'https://acg.284164.xyz/pe.php?return=all'

## Error behavior

- Unsupported HTTP method: 405, Allow: GET, HEAD.
- Invalid return parameter: 400 JSON.
- Unknown path or invalid image filename: 404 text/plain.
- Empty image pool: 503 JSON.

## Caching

Random endpoints use Cache-Control: no-store.
Image assets use Cache-Control: public, max-age=31536000, immutable.