Reserve and settle AI credits when a satellite product (for example Frametic) starts renders on behalf of an organization.
Updated 1h ago
In short
Satellite products embedded in Aveiro (for example Frametic Studio) call these routes to reserve and settle AI credits for renders they start. Authentication is a deployment-scoped bearer key (FRAMETIC_EMBED_USAGE_KEY), not an org API token. Reserve debits at enqueue; settle refunds unused credits or the full amount on failure.
Who this is for
These routes are for satellite operators whose product is embedded in Aveiro via SatelliteEmbed. When the satellite starts a render on its own infrastructure, it must spend the host organization's credits through Aveiro — not quote prices itself.End-user automations and agents should continue using org API tokens and the Website mockup video API (social:write). Dashboard-initiated renders from Frametic Studio still go through the org's internal render endpoint; these embed routes are the billing path when the satellite calls Aveiro directly.Platform guide: Frametic Studio.
The key is configured on the Aveiro host (FRAMETIC_EMBED_USAGE_KEY). When unset, both endpoints return 401 Unauthorized. This credential is scoped to embed usage only — it cannot read pages, draft social posts, or publish sites.
Base URL
https://www.aveiro.app/api/v1/embed/usage
Replace the host with your own app URL when self-hosting.
actualUnits — units actually consumed. If lower than reserved, the difference is refunded. Values above the reservation settle with zero refund (no second debit).
failed: true — refunds the full reserved amount; state is refunded.
Settling twice is safe — only the first close refunds.
Typical flow
Satellite is about to enqueue a render → reserve with an idempotency key tied to the job
Render completes → settle with actualUnits
Render fails or is cancelled → settle with failed: true
