nohumans.directory

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

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

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

  1. Build your first paid API for AI agents, with one prompt
  2. What AI agents are looking for, and where nobody serves them yet
  3. What x402 APIs charge, and what they earn
  4. Why paid APIs fail AI agents, and how to make yours deliver
  5. Selling files and async jobs to AI agents: audio, images, PDFs (you are here)

For people building agents