Metered pay-per-use call

The response body is the RAW upstream response (byte-compatible with the provider SDK shape). Cost rides in response headers. X-Locus-End-User present (or an end-user token or end-user-bound Agent Connection) charges that user's account at your effective price; a secret-key call without it or a platform-mode Agent Connection charges your platform account at base price with zero markup.

post/wrapped/credits/{provider}/{endpoint}

Request

Base URL
https://api.paywithlocus.com/api
URL
https://api.paywithlocus.com/api/wrapped/credits/{provider}/{endpoint}
Auth
- HTTP bearer
- or HTTP bearer
- or HTTP bearer
- or HTTP bearer

Path parameters

providerstring required

endpointstring required

Headers

X-Locus-Max-Charge-Creditsstring

Hosted wrapped APIs: hard per-call ceiling in tenant credits, including applicable markup. Rejected with 409 charge_ceiling_exceeded before reservation or upstream dispatch if exceeded. Applies to fal generation reservations. Not forwarded upstream.

X-Locus-Session-Idstring

Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication.

Idempotency-Keystring required

Required. Missing → 400. Same key + different body → 409. Retries replay the stored outcome for 24 hours after the call; after that the key is released and reusing it starts a new call.

Preferstring

Example:respond-async

respond-async: answer 202 with the apiCallId once the provider request is sent, and finish the call in the background. Read the outcome from resultUrl (POST /wrapped/credits/calls/{callId}/result). Anything decided before dispatch (validation, balance, policy, a replay) answers as usual. Ignored when stream is true.

X-Locus-End-Userstring

Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

Request body

object required

Upstream-shaped request body (see the per-endpoint docs at /credits/md)

Response

Raw upstream response. For fal/generate this acknowledges queue submission: credits remain reserved until a background reconciler confirms the result. Confirmed failures release the hold; successful results capture it. Read /wrapped/credits/calls/{callId} for settlement status.

Changes

No recorded changes to this operation across all 1 revision of this API.