An agent-ready API is one a coding agent can discover, authenticate against, call, and bill against without a human reading HTML or completing an OAuth redirect. It ships machine-readable docs (llms.txt and llms-full.txt), an executable setup prompt the agent can run, an MCP server with a finite tool list, SDKs in the languages the agent already writes, and auth plus billing that reduce to one secret and a unit the agent can cap. A human-only API can look finished in a browser and still fail that test: the docs are HTML, login is a dance, and the meter is currency with no hard stop.
The test is whether a process can finish the job
Hand a coding agent a typical generation API and watch where it breaks. It fetches a docs page and copies the nav, the copy-button label, and a cookie banner into the prompt. It invents a parameter name that was never on this API. It starts a PKCE flow it cannot complete in a terminal. It writes a polling loop around a call that already returned a file. It has no idea what a dollar on a card will buy, so it cannot refuse a retry.
Those failures are the API's shape, not the model's. The human path — open the docs, click Authorize, paste a token — was never encoded as something a process can execute.
An agent-ready API is the same product with a second reader in mind. The human still gets a playground and HTML. The agent gets files it can fetch, a checklist it can run, tools it can call, and a meter it can reason about. If any of those is missing, the agent improvises. Improvisation on a billable endpoint is a wrong path and a real charge.
PicX is built for that second reader. One REST API at https://api.picxstudio.com. One key with a pxsk_ prefix. Auth is a single header:
Authorization: Bearer $PICX_API_KEYRoughly 33 image and video models sit behind that key. What follows is the checklist that makes that key usable from a coding agent.
Machine-readable docs are a contract, not a scrape
HTML documentation is for people. A model that fetches the rendered page gets chrome: nav labels, "Copy" on every snippet. The parameter table arrives without a fence around the example. That blob is a bad prompt.
llms.txt is the index: title, one-line summary, URL per page, cheap enough to fetch first. llms-full.txt is the same documentation concatenated, for the case where loading the whole reference in one request is cheaper than walking the index. Both are markdown. Both have to be generated from the same source the HTML is generated from. If they drift, the agent is worse off than if the files did not exist.
Live copies of both sit on the PicX developer site. Individual pages are also available as markdown. An agent asked to integrate should fetch https://picxstudio.com/llms.txt before it writes a single call. Training data is not the source of truth. The file is.
This is not a sitemap. A sitemap lists URLs. llms.txt lists what each URL is for. Generate the index and the HTML from one markdown tree, or you will ship two docs.
An executable setup prompt is not a quickstart
A getting-started page tells a human which commands to run. An executable setup prompt tells the agent to run them.
The pattern is one URL. The file is addressed to the agent: detect the project language, install the SDK, ask the human for the one secret the agent cannot mint, write it to an env file that is gitignored, make one real call, stop. It does not print a tutorial.
PicX ships that file at https://picxstudio.com/developers/agent-setup/prompt.md. The llms.txt index points at it. Paste the URL into Claude, Cursor, or any agent that fetches the web and say "do this."
One step stays human. Creating a pxsk_ key requires a signed-in session on the dashboard. There is no unauthenticated mint endpoint, and there should not be one. The prompt is explicit: ask for the key, store it as PICX_API_KEY, never commit it. Everything else is the agent's. A prompt that claims a surface that 404s is worse than no prompt — the agent will try, fail, and invent a workaround. Only list what is live.
MCP is a finite tool list, not a second docs site
Docs tell the agent what HTTP looks like. MCP lets it skip HTTP inside the chat client.
The server advertises tools: names, descriptions, JSON schemas. The model fills arguments. The client posts the call with your auth header. The result that matters is still an HTTPS URL, not a path on the machine that ran the call.
PicX's MCP server is documented at https://picxstudio.com/developers/mcp. It exposes 19 tools covering generation, edits, assets, and account lookups. Auth is the same Bearer header as the REST API. There is no OAuth flow and no session cookie. Connection pages exist for Claude Desktop, Cursor, and ChatGPT (https://picxstudio.com/developers/mcp).
Fourteen is a number you pick on purpose. A catalog of hundreds of tools is a retrieval problem the model will lose. One generate tool with no edit, no account lookup, and no way to list models is too thin. The right size is the jobs the agent actually runs, plus the lookups it needs before it spends.
MCP is not a substitute for REST. Scripts, CI, and backend routes should hit https://api.picxstudio.com. MCP matches how Claude Desktop, Cursor, and ChatGPT already invoke tools. Agent Skills at https://picxstudio.com/skills cover the same platform for clients that load skills instead of, or in addition to, MCP. If pixels cannot leave your machine, run a local model — and then you still have to host the file and write the server.
SDKs the agent can install without guessing the package name
An agent that has to invent an import path will invent a wrong one. Official packages with a stable name on the registries it already uses are part of the API, not a side project.
PicX ships picx-ai on npm and on PyPI, a CLI. The interactive playground is for the human who wants to see a request before they paste a key into an agent. Same API. Same key. Same hosted URL on the way out.
Python and JavaScript cover the two ecosystems coding agents write into most often. Swift covers shipping the same generate call in an iOS app without a Node wrapper. If your runtime is none of those, the REST API is still one URL and one header. Document the install command as a literal: npm install picx-ai, pip install picx-ai.
Auth and billing a process can reason about
OAuth is correct for a third-party app acting as a user in a browser. It is a poor fit for a coding agent in an editor. Redirect URIs, PKCE, refresh tokens, and a consent screen are a human protocol. The agent cannot click Allow. Most MCP clients will not forward a session cookie either.
Bearer API keys are the agent-shaped alternative. One header, every request. Keys start with pxsk_. One key reaches the REST API, the MCP server, the CLI, and the SDKs. Scope it to what the agent should do. Cap it. Rotate it if a config file leaked. Do not put it in a client-side bundle.
Billing is the other half. Currency on a card is not a unit a model can cap. "Stop before this costs ten dollars" requires the agent to know the price of a generation and whether a retry double-charges. Most agents do not. They retry.
Credits per generation are a countable unit. Hard spend caps on a key are the stop: the agent can keep retrying and the key will refuse. PicX bills that way — credits per generation, never a currency amount on the meter — and you can set those caps on a key before you paste it into a chat client. A cap is not a substitute for reviewing tool calls while you are still prompting. It is the last line, not the first.
The response has to be something the next tool can fetch
An agent does not want a job id for a still image if the image can come back in the same body. Polling is extra state, extra tokens, and extra chances to loop. PicX image generation is synchronous: a simple generate call returns a hosted image URL in the response. There is no poll on that path.
Video and batch take longer. Those jobs are asynchronous and delivered by webhook. That is the honest split. Pretending video is synchronous hangs the client. Pretending a still is a job makes the agent write a wait loop it does not need.
The URL has to live somewhere the rest of the toolchain can GET. We store output on PicX's own CDN. You do not bring a bucket. You do not configure a second host. The agent embeds the URL. A README fetches it. An edit call takes it as input.
You give up private object storage you operate. If the pixels cannot leave your network, this shape is wrong for you: you will run a model and a bucket, and the agent will need both credentials.
What agent-ready does not buy you
It does not make the language model a photographer. Bad prompts still produce bad pictures. Iteration needs an edit path that accepts the previous URL.
It does not replace SVG for icons and diagrams. Do not route every "draw" through an image model.
It does not mean every endpoint should be an MCP tool. Account mutations, destructive deletes, and anything that spends a lot should stay behind approval or off the tool list.
It does not remove the human from key creation. If your onboarding includes a mint-a-key URL with no login, you have a security incident, not a setup prompt.
The work sits on the vendor. HTML docs, a playground, and a dashboard are the human product. llms.txt, prompt.md, MCP, SDKs, Bearer auth, credit caps, synchronous image generation, hosted URLs — that is the agent product. Shipping only the first list is how you get hallucinated parameters and a surprise bill.
FAQ
What makes an API agent-ready rather than just well documented?
An agent-ready API ships machine-readable docs (llms.txt and llms-full.txt), an executable setup prompt, an MCP server, installable SDKs, and auth plus billing a process can complete and cap. HTML pages a human can click through are necessary. They are not sufficient.
Why isn't OAuth a good default for coding agents?
OAuth assumes a browser, a redirect, and a human clicking Allow. A coding agent in an editor needs a Bearer key it can send on every request, scoped and spend-capped, without completing a PKCE flow or storing a refresh token.
Does PicX require polling for a simple image generate?
No. A simple image generate call is synchronous and returns a hosted CDN URL in the response body. Video and batch jobs are asynchronous and delivered by webhook.
Where should a coding agent start if it needs to integrate PicX?
Fetch https://picxstudio.com/llms.txt as the index, then run https://picxstudio.com/developers/agent-setup/prompt.md. MCP, Skills, the CLI, and the picx-ai SDKs use the same pxsk_ key against https://api.picxstudio.com.
