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 Faker Studio'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 Faker Studio 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/faker-studio/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

bash

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

Response

json

{
  "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/faker-studio/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

bash

curl -X POST "https://yoursite.com/wp-json/faker-studio/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

json

{
  "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/faker-studio/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

bash

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

Response

json

{
  "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/faker-studio/v1/media/upload-url

Parameters

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

Example Request

bash

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

Response

json

{
  "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/faker-studio/v1/media/upload

Request Format

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

Example Request

bash

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

Response

json

{
  "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 _faker_studio_uploaded post meta flag, which allows Faker Studio's cleanup tools to identify and remove them when needed.

Media Endpoints ​

Get Media Library Images ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Download Images ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Get Media Library Files ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Upload Image from URL ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Upload File ​

Endpoint ​

Request Format ​

Example Request ​

Response ​

Error Responses ​

Media Endpoints

Get Media Library Images

Endpoint

Parameters

Example Request

Response

Download Images

Endpoint

Parameters

Example Request

Response

Get Media Library Files

Endpoint

Parameters

Example Request

Response

Upload Image from URL

Endpoint

Parameters

Example Request

Response

Upload File

Endpoint

Request Format

Example Request

Response

Error Responses