Media Endpoints

The media endpoints manage images and files in the WordPress media library. They allow you to browse existing media, download images from external providers, import files from URLs, and upload files directly. These endpoints power WPfaker's media management UI and are useful for pre-populating a media library before generating posts that reference images and files.

Every media endpoint requires administrator permissions. Responses follow the standard WPfaker JSON format with success: true and the data nested appropriately.

TIP

For general information about authentication, error codes, and response format, see the REST API Overview.

Get Media Library Images

Retrieve images from the WordPress media library with pagination and search. This endpoint returns image attachments suitable for use in custom field configurations and template image selection.

Endpoint

GET /wp-json/wpfaker/v1/media/images

Parameters

Parameter	Type	Default	Description
per_page	integer	20	Number of images per page
page	integer	1	Page number
search	string	—	Search term to filter images by title

Example Request

curl "https://yoursite.com/wp-json/wpfaker/v1/media/images?per_page=10&page=1" \
  -H "X-WP-Nonce: your-nonce"

Response

{
  "success": true,
  "images": [
    {
      "id": 142,
      "title": "Mountain Landscape",
      "url": "https://yoursite.com/wp-content/uploads/2025/01/mountain-landscape.jpg",
      "thumbnail": "https://yoursite.com/wp-content/uploads/2025/01/mountain-landscape-150x150.jpg",
      "medium": "https://yoursite.com/wp-content/uploads/2025/01/mountain-landscape-300x200.jpg",
      "dimensions": "1200x800",
      "ratio": "3:2",
      "generated": true
    },
    {
      "id": 143,
      "title": "City Skyline",
      "url": "https://yoursite.com/wp-content/uploads/2025/01/city-skyline.jpg",
      "thumbnail": "https://yoursite.com/wp-content/uploads/2025/01/city-skyline-150x150.jpg",
      "medium": "https://yoursite.com/wp-content/uploads/2025/01/city-skyline-300x200.jpg",
      "dimensions": null,
      "ratio": null,
      "generated": false
    }
  ],
  "total": 143,
  "total_pages": 8,
  "page": 1
}

---

Download Images

Download images from an external image provider directly into the WordPress media library. This is useful for pre-populating the media library before generating posts, or for adding stock images in bulk.

Endpoint

POST /wp-json/wpfaker/v1/media/download

Parameters

Parameter	Type	Default	Description
count	integer	5	Number of images to download (1--20)
provider	string	"picsum"	Image provider slug (see Image Providers)
category	string	""	Image category (only for providers that support categories)
width	integer	1200	Image width in pixels (100--4000)
height	integer	800	Image height in pixels (calculated from aspect ratio if not set)
aspect_ratio	string	"3:2"	Aspect ratio for calculating height from width
random_size	boolean	false	Use random dimensions within a range instead of fixed size
width_min	integer	800	Minimum width when random_size is true (100--4000)
width_max	integer	1600	Maximum width when random_size is true (100--4000)

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/media/download" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 5,
    "provider": "picsum",
    "width": 1200,
    "aspect_ratio": "16:9"
  }'

Response

{
  "success": true,
  "message": "5 Bilder heruntergeladen",
  "count": 5,
  "images": [
    {
      "id": 201,
      "title": "picsum-1200x675-a3f2c1",
      "url": "https://yoursite.com/wp-content/uploads/2025/01/picsum-1200x675-a3f2c1.jpg",
      "thumbnail": "https://yoursite.com/wp-content/uploads/2025/01/picsum-1200x675-a3f2c1-150x150.jpg",
      "dimensions": "1200x675",
      "ratio": "16:9"
    }
  ]
}

INFO

The count parameter is capped at 20 per request to prevent timeouts. For larger batches, make multiple requests. Each downloaded image is added to the WordPress media library as a standard attachment and can be used anywhere media is referenced.

---

Get Media Library Files

Retrieve non-image files from the WordPress media library. This endpoint returns documents, PDFs, spreadsheets, and other file attachments — useful for populating file-type custom fields.

Endpoint

GET /wp-json/wpfaker/v1/media/files

Parameters

Parameter	Type	Default	Description
per_page	integer	50	Number of files per page
page	integer	1	Page number
file_type	string	—	Filter by file category: pdf, document, spreadsheet, or archive

Example Request

curl "https://yoursite.com/wp-json/wpfaker/v1/media/files?per_page=20&file_type=pdf" \
  -H "X-WP-Nonce: your-nonce"

Response

{
  "success": true,
  "files": [
    {
      "id": 301,
      "title": "Sample Contract",
      "filename": "sample-contract.pdf",
      "url": "https://yoursite.com/wp-content/uploads/2025/01/sample-contract.pdf",
      "mime_type": "application/pdf",
      "extension": "pdf",
      "filesize": 245760,
      "uploaded": true
    }
  ],
  "total": 12,
  "total_pages": 1,
  "page": 1
}

---

Upload Image from URL

Import an image or file from an external URL into the WordPress media library. The file is downloaded, validated against WordPress's allowed file types, and added as a standard media attachment.

Endpoint

POST /wp-json/wpfaker/v1/media/upload-url

Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL of the file to import

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/media/upload-url" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

Response

{
  "success": true,
  "message": "Datei erfolgreich hochgeladen",
  "file": {
    "id": 401,
    "title": "photo",
    "url": "https://yoursite.com/wp-content/uploads/2025/01/photo.jpg",
    "filename": "photo.jpg"
  }
}

WARNING

The file type must be allowed by WordPress. If the URL points to a file with an unrecognized or disallowed extension, the upload is rejected with a "file type not allowed" error. Check WordPress's allowed MIME types in Settings > Media if you encounter this issue.

---

Upload File

Upload a file directly from the local filesystem via multipart form data. The file is validated and added to the WordPress media library as a standard attachment.

Endpoint

POST /wp-json/wpfaker/v1/media/upload

Request Format

This endpoint expects a multipart/form-data request with the file in a field named file.

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/media/upload" \
  -H "X-WP-Nonce: your-nonce" \
  -F "file=@/path/to/document.pdf"

Response

{
  "success": true,
  "message": "Datei erfolgreich hochgeladen",
  "file": {
    "id": 501,
    "title": "document",
    "url": "https://yoursite.com/wp-content/uploads/2025/01/document.pdf",
    "filename": "document.pdf"
  }
}

Error Responses

Upload errors return descriptive messages:

Error	Message
No file provided	"Keine Datei hochgeladen"
File too large (PHP limit)	"Datei zu groß (PHP-Limit)"
File too large (form limit)	"Datei zu groß (Formular-Limit)"
Partial upload	"Datei nur teilweise hochgeladen"
Missing temp directory	"Temporäres Verzeichnis fehlt"
Write error	"Fehler beim Schreiben der Datei"
Disallowed type	"Dateityp nicht erlaubt"

INFO

Both upload endpoints (upload-url and upload) mark uploaded files with the _wpfaker_uploaded post meta flag, which allows WPfaker's cleanup tools to identify and remove them when needed.