Run a capability
POST /v1/capabilities//run
GET /v1/tools and returns its result on the same request. There is no job to poll and no streaming, so a slow capability holds the connection for its whole duration.
Authorizations
API key in format: Bearer inf_***
Path Parameters
Capability to run — one of the data[].id values from GET /v1/tools, e.g. image.resize. Also the identity the quota, allowed-model and budget checks are applied against.
Body
Response
The capability result. File-producing capabilities answer file_id (plus url/mime/size_bytes when the engine reported them); text-producing ones answer result.
Identifier for this run — the literal prefix cap_ followed by a UUID.
"cap_1f0c2b7e-6b2a-4a1f-9a54-3d1f8b0c2a11"
The capability that ran — echoes the id path parameter.
"image.resize"
Credits settled for this run (1 credit = $0.01). 0 when the capability has no priced catalogue entry, in which case the run was not billed — 0 means unbilled, not free by policy. May be fractional.
0.5
Identifier of the ApiFile the engine registered for the produced bytes, usable with GET /v1/files/{fileId} and GET /v1/files/{fileId}/content. Present only for capabilities that produce a single stored artifact; absent for text-producing capabilities and for archive.unpack, which produces many artifacts and reports them inside result instead.
"file_1hR9xTPZqK4mVLc2nJ7fY5wB"
Where the engine reported those bytes can be read. Only ever present alongside file_id, and only when the engine supplied it.
MIME type the engine reported for the produced file. Only ever present alongside file_id, and only when the engine supplied it.
"image/png"
Size of the produced file in bytes. Only ever present alongside file_id, and published only when the engine reported a usable non-negative integer.
245192
The capability's own output body, for capabilities that produce no single stored file — web.search, code.run_python, code.run_node, and archive.unpack (whose per-entry object URIs are stripped before it leaves the gateway). Also present alongside file_id for a capability that returns text beside its artifact, such as document.extract_text. The shape is defined by the capability and is not modelled here.