Upload a file from a URL

Provide an HTTPS URL and the server fetches + stores the file. Ideal for bots that receive temporary file URLs (Discord, Slack, webhooks). Private IPs and internal hostnames are blocked (SSRF protection). Takes the same optional headers as /v1/aion/upload: Idempotency-Key, X-Price-Per-Download, X-Payout-Address, X-Listing-Intent and X-Wait-For-Ready. The API key is optional; a keyless caller uploads as a guest.

post/v1/aion/upload-url

Request

  • Base URL: https://api.payaion.com
  • URL: https://api.payaion.com/v1/aion/upload-url
  • Auth: one of:
    • none
    • API key in header X-Aion-Key

Headers

Idempotency-Keystring

Optional key for retry-safe requests

X-Price-Per-Downloadnumber

Price per download in USD (e.g. 0.50). When set, downloaders must pay this amount in USDC to access the file. Omit or set to 0 for free downloads. A positive price below 0.000001 rounds to zero atomic USDC and is rejected as invalid_price.

A price needs somewhere to pay: either the account's payout address, or X-Payout-Address for a keyless caller. Otherwise 400 wallet_required.

X-Payout-Addressstring

Where a keyless seller's earnings go — this is what lets an agent sell with no account. Honoured for keyless callers only: when a key is sent, that account's payout address is a dashboard setting and this header is ignored, so a key can never redirect an account's earnings.

Pricing without a key gives the file a 14-day window instead of 24 hours (nobody can buy inside a day) and is capped to a few uploads per day per network address.

X-Listing-Intentstring

JSON object that lists the file on the marketplace once it is READY: title (required, 3-120 characters), description (required, 40-500 characters), category (optional: reports, datasets, code, media, models, prompts, other) and tags (optional, max 8, each up to 30 characters of a-z, 0-9 and hyphens).

Needs an API key with the marketplace:list scope; a keyless caller gets 403 forbidden. Header values must be ASCII, so escape other characters as \uXXXX. Invalid JSON or a field that breaks a rule fails the upload with 400 invalid_listing_intent. The listing spends the daily listing quota: over it, the file is still uploaded and the response carries listingSkipped instead of url.

X-Wait-For-Ready'true'

true holds the request until the upload is READY (up to about two minutes) and answers 200 with ready. If no wait slot is free the server answers 202 with waitUnavailable: true; poll the status URL.

Request body

urlstring uri required

HTTPS URL of the file to fetch (Basic 500 MB / Pro 1 GB)

fileNamestring

Optional filename override (derived from URL if omitted)

Example request

{
  "url": "https://cdn.example.com/photo123.jpg",
  "fileName": "photo123.jpg"
}

Response

Returned when X-Wait-For-Ready held the request until the upload finished or the wait ran out

uploadIdstring required
statusstring required

READY on success, otherwise the last status seen (for example FAILED or TIMEOUT)

readyboolean required
statusUrlstring required
downloadUrlstring uri required
expiresAtstring date-time required
pricePerDownloadstring nullable

Price per download in USD (present only when set)

urlstring uri

Market page (/m/{hash}), present when the listing was created

Example response

{
  "uploadId": "up_a1b2c3d4e5f6g7h8",
  "status": "READY",
  "statusUrl": "/v1/upload/up_a1b2c3d4e5f6g7h8/status",
  "downloadUrl": "https://payaion.com/d/abc123xyz789",
  "pricePerDownload": "0.50",
  "url": "https://payaion.com/m/abc123xyz789"
}

Changes

No recorded changes to this operation across all 1 revision of this API.