Guides › Selling to AI agents, part 5 of 5
Selling files and async jobs to AI agents: audio, images, PDFs
Published 10 November 2026. Figures are from our own purchases, read on that date; library behaviour was checked in
@x402/hono and @x402/core 2.29.0.
Updated 18 November 2026: a paid 202 that tells the agent where or how to collect the result — a URL, a path, a job id or a token — is no longer recorded as a failed delivery. Until we go back for the result it is recorded as accepted_not_followed, an outcome we do not count for or against the seller; 10 earlier purchases were corrected. A 202 with nothing to follow is still a failure. The advice below is unchanged: a full status URL is the shape every agent can follow (correction #29; shared definition: x402 vocabulary 1.0, §4.2).
Most paid APIs answer with a small piece of JSON. Some sell something else: a voice clip, an image, a PDF, or a job that takes a minute to finish. These can sell well, because an agent cannot easily make them itself. But they fail in ways a JSON API never does, and the failures look like the seller’s fault even when the work was done.
We buy paid APIs with real USDC and record what came back. Until 9 November our own checks expected JSON, so every
real file we bought was recorded as a failure. We fixed that and bought 20 of those APIs again: 16 delivered, among them PNG
images, WAV and MP3 audio, PDFs and a WebP image. Separately, 20 of our paid calls were answered with 202 Accepted, on
8 different hosts, and that one status meant two different things. This guide is what we learned from both.
Returning a file
Send the file itself, with the right type
Answer the paid request with the file’s bytes and a Content-Type that says what they are:
audio/mpeg, image/png, application/pdf. A buyer checking the answer can then see it
is a real file, not an error page. Say the same in the payment challenge: the x402 middleware takes a mimeType
in each route’s settings and publishes it with the price, so an agent knows before paying that it will get audio, not
JSON.
Never send an error with a file’s type. A JSON error labelled audio/mpeg, or an HTML page labelled
image/png, is worse than an honest error: the agent paid, and what it got is neither the file nor a message it
can read. Errors go out as JSON with a 4xx or 5xx status, and the standard middleware then does not take the payment.
Offer JSON too
Many agents work in text and JSON, and a tool call inside an AI assistant often cannot carry raw bytes. An option that returns the file inside JSON lets them use you anyway:
{"content_type": "audio/mpeg", "bytes": 48213, "sha256": "…", "audio_base64": "SUQzBAAAAAAA…"}
Keep the file as the default, and switch on a parameter such as response_format=json. Put that parameter in
your example input, so an agent that reads your listing finds it.
Keep paid files small, or send a link
The x402 middleware holds the whole answer in memory until the payment settles, then sends it: on Cloudflare Workers that is fine for a few megabytes, not for a video. For large files, answer with JSON that carries a download link valid for a while, plus the size and a checksum, and make the link itself free: the agent has already paid.
Long jobs: 202 Accepted
What 202 means to an agent
If the work takes longer than a request can wait, accept the job and answer 202 Accepted. Be aware that the
standard middleware takes the payment on any answer below 400, so a 202 is charged when the job is accepted, not when it
finishes. That is fair only if the agent can get the result without paying again.
Of those 20, 14 were real jobs: the answer carried a job id. Where to check on it came in four shapes: a full URL, a path to add to the host, a token with no address at all, or only a sentence in a message (“check status with /v1/requests/{id}”). An agent can follow the first. It has to guess at the second, and cannot use the last two.
A 202 an agent can follow
- A full status URL in the body (
status_url) and in theLocationheader, with aRetry-Afterheader saying how many seconds to wait. - The same job id in the 202 and in the finished result, so the agent can match them.
- A free status URL. Protect it with a token in the URL, not with a second payment.
- A plain status field:
queued,running,doneorfailed; when done, the result or a link to it; when failed, why. - Results kept for at least a day, so an agent that checks late still gets what it paid for.
HTTP/1.1 202 Accepted
Location: https://api.example.com/v1/jobs/job_8139?token=jt_c254
Retry-After: 20
{"job_id": "job_8139", "status": "queued",
"status_url": "https://api.example.com/v1/jobs/job_8139?token=jt_c254"}
Do not use 202 for “payment pending”
The other 6 were not jobs at all. They meant “we have not confirmed your payment yet, do not pay again”, with no result and no job to check. To an agent that looks exactly like a job it cannot follow. If you must answer before a payment is confirmed, say so in a field an agent can read, include the transaction, and keep the result available for when it is. Better still, wait for the confirmation and answer once.
Make the first purchase work
Whatever you return, an agent’s first call succeeds only if it can tell what to send. Give a request schema and a real example input in your listing and in the payment challenge’s discovery extension, and a free sample route that shows a real answer: a short clip, a small image, a one-page PDF. Part 4 covers the other ways paid APIs fail.
A prompt that does this for your API
Paste this into your AI assistant, in the project of your API.
My paid x402 API returns [a file: audio / an image / a PDF] [or: results of long jobs]. Review it against these rules and fix what does not match, explaining each change in plain words, then test it before telling me it works: 1. A successful paid answer sends the file's bytes with the correct Content-Type, and the route's x402 settings declare the same mimeType. 2. Errors are JSON with a 4xx or 5xx status, never labelled as a file type, so the payment is not taken. 3. Add an option (response_format=json) that returns the file inside JSON: content_type, bytes, sha256 and the file as base64, and put it in the example input. 4. Files larger than a few MB are returned as JSON with a free download link that stays valid for at least a day, plus size and checksum. 5. If a job takes longer than a request can wait: answer 202 with job_id, a full status_url in the body and the Location header, and Retry-After; the status URL is free (protected by a token in the URL), reports queued / running / done / failed, includes the same job_id, and keeps results for at least a day. 6. Never answer 202 to mean "payment not confirmed yet". 7. The listing and the payment challenge carry a request schema, a real example input, and a free sample route with a small real answer. When it works, check it free at https://api.nohumans.directory/v1/check and update the listing at https://nohumans.directory/submit.
Your next step
- Know when a purchase fails. Free alerts send you a signed webhook when we buy your API, delivered or not, and when its status or price changes.
- See your listing as agents do. Your numbers, free: the searches you show up for, and the ones that went to others.
- Not listed yet? Check it free and list it where agents look for paid services.
Sources: nohumans.directory purchase records (our re-purchases of 9 November 2026; every paid call answered
202 up to 10 November); @x402/hono 2.29.0 (settles below status 400, after buffering the answer) and
@x402/core 2.29.0 (route mimeType published with the payment request). Method:
a real media file counts as delivered.
← Part 4: Why paid APIs fail AI agents, and how to make yours deliver
Selling to AI agents: the series
- Build your first paid API for AI agents, with one prompt
- What AI agents are looking for, and where nobody serves them yet
- What x402 APIs charge, and what they earn
- Why paid APIs fail AI agents, and how to make yours deliver
- Selling files and async jobs to AI agents: audio, images, PDFs (you are here)