> ## Documentation Index > Fetch the complete documentation index at: https://docs.infery.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a capability > POST /v1/capabilities/{id}/run Executes one capability from [`GET /v1/tools`](/api-reference/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. This is billed. Credits are reserved before the work starts and settled against what it actually used. ## OpenAPI ````yaml openapi.json POST /v1/capabilities/{id}/run openapi: 3.0.0 info: title: Infery Gateway description: >- Infery Inference Gateway — OpenAI-compatible API for LLMs, embeddings, images, audio, and video version: '1.0' contact: {} servers: - url: https://api.infery.ai description: Production - url: http://localhost:3001 description: Local security: [] tags: [] paths: /v1/capabilities/{id}/run: post: tags: - capabilities summary: Run a single capability synchronously description: >- Executes one capability from `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. This is BILLED. Credits are reserved before the engine runs and settled against what the engine measured; `credits_used` on the response is the settled amount. The API key's rate limit, allowed-model list and budget are all enforced against the capability id BEFORE any billable work starts. `input` and `params` are validated against that capability's published Zod schemas before the engine is touched, so a shape error costs nothing. An unrecognised capability id is likewise a 400 (with near-miss suggestions), not a 404. It runs exactly one capability and does not chain: feeding one capability's artifact into another is what a workflow is for. operationId: runCapability parameters: - name: id required: true in: path schema: type: string description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunCapabilityDto' responses: '200': description: >- The capability result. File-producing capabilities answer `file_id` (plus `url`/`mime`/`size_bytes` when the engine reported them); text-producing ones answer `result`. content: application/json: schema: $ref: '#/components/schemas/CapabilityRunResultDto' '400': description: Invalid request / unknown capability id content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '401': description: Unauthorized — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '403': description: Quota exceeded (rate limit / model not allowed / budget) content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - ApiKey: [] components: schemas: RunCapabilityDto: type: object properties: input: type: object description: >- Capability input payload (shape defined by the capability's zod input schema). params: type: object description: >- Capability params payload (shape defined by the capability's zod params schema). CapabilityRunResultDto: type: object properties: id: type: string description: >- Identifier for this run — the literal prefix `cap_` followed by a UUID. example: cap_1f0c2b7e-6b2a-4a1f-9a54-3d1f8b0c2a11 capability: type: string description: The capability that ran — echoes the `id` path parameter. example: image.resize file_id: type: string description: >- 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. example: file_1hR9xTPZqK4mVLc2nJ7fY5wB url: type: string description: >- Where the engine reported those bytes can be read. Only ever present alongside `file_id`, and only when the engine supplied it. mime: type: string description: >- MIME type the engine reported for the produced file. Only ever present alongside `file_id`, and only when the engine supplied it. example: image/png size_bytes: type: integer description: >- 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. example: 245192 result: type: object additionalProperties: true description: >- 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. credits_used: type: number description: >- 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. example: 0.5 required: - id - capability - credits_used ErrorResponseDto: type: object properties: error: description: >- The error envelope. Every non-2xx response from this API has this shape, so a client can parse failures without branching on the endpoint. allOf: - $ref: '#/components/schemas/ErrorDetailDto' required: - error ErrorDetailDto: type: object properties: message: type: string example: Model not found description: Human-readable error message type: type: string example: invalid_request_error description: Error category enum: - invalid_request_error - authentication_error - permission_error - quota_exceeded - rate_limit_error - server_error code: type: string example: model_not_found nullable: true description: >- Stable machine-readable error code. Branch on this rather than on `message`, which is prose and may be reworded. param: type: string example: model nullable: true description: >- Name of the request parameter that triggered the error. `null` when the error is not attributable to one field. job_id: type: string example: job_1hR9xTPZqK4mVLc2nJ7fY5wB description: >- Handle to work that is ALREADY RUNNING AND ALREADY BILLED, present on the few errors that carry one. When it is here, this is not a failure to retry — retrying pays twice. Collect the result from `GET /v1/images/jobs/{job_id}`, which serves every durable media job regardless of modality. Two situations produce it. A media generation that outruns the gateway's wait answers `504` with `code: "job_timeout"` and keeps working. And `POST /v1/audio/speech` answers **500** with `code: "artifact_unreadable"` when the speech was generated and settled but could not be read back from storage — the audio exists and is paid for; only this response failed. Declared here rather than per-endpoint because the rule is about the FIELD, not the status: if this is present, there is a paid-for result to collect. It was undeclared until now, so a client generated from this document could not see the one field that recovers money already spent. required: - message - type - code - param securitySchemes: ApiKey: type: apiKey in: header name: Authorization description: 'API key in format: Bearer inf_***' ````