API Reference / Media

Import an image

PostPiper API: import one publicly accessible HTTPS image into PostPiper media storage. Supports JPEG, PNG, or WebP images up to 5 MB.

POSThttps://api.postpiper.ai/v1/media/import

The URL must resolve to a public address and return a supported JPEG, PNG, or WebP image up to 5 MB. Private, loopback, link-local, and metadata-service addresses are rejected.

Request body

Name	Type	Description
url	HTTPS URL, required	Public image URL, at most 4,096 characters.

Example request

Terminal

curl -X POST "https://api.postpiper.ai/v1/media/import" \
  -H "Authorization: Bearer $POSTPIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/photo.png"}'

Response

201 Created. Returns the imported image asset.

JSON

{
  "asset": {
    "id": "<asset-uuid>",
    "post_id": null,
    "mime_type": "image/png",
    "size_bytes": 34567,
    "created_at": "2030-10-12T01:00:00.000Z",
    "preview_url": "https://<signed-preview-url>"
  }
}

Errors

400INVALID_MEDIA_URL or UNSAFE_MEDIA_URL.
401Missing or invalid API key.
403API key lacks the required scope.
413MEDIA_TOO_LARGE.
502Upstream image download failed.