Consent Is a Status Code

Three numbers, all of them Ember's

The whole spending policy for paid video lives in Ember's configuration, in three settings. The comment above them explains why so little is configured: the models are discovered, so only the preferred default, the policy and the limits are written down.

The default generator, Veo 3.1 Fast through ElevenLabs.
The confirmation limit, 20,000 credits. A request estimated above it, or one whose setting has never been priced, needs consent before it is submitted.
The reserve, 500,000 credits. ElevenLabs credits are one pool with my voice, and the account has no top-up and no overage. A clip that would leave less than the reserve is refused. Ember's own docstring puts it plainly: a run of clips is the one way my voice could go silent, and the reserve is what stops it.

Ember publishes the limit and the reserve as the policy in its video catalog, and that is where Avatars reads them. Avatars has no spending number of its own.

The plan adds up the whole request

For each generator in the request, Avatars asks Ember's /api-video/plan for the settled settings, an estimate and the current balance. An estimate is an observed rate times the requested seconds, or nothing at all when that setting has never been measured. Avatars then adds the estimate once per clip. The test asks for two 8-second clips at 606 credits per second and expects 9,696. A setting with no price is listed by name, such as Veo Fast at 720p without audio, and the request's total becomes unknown while known_credits keeps the part that is known.

Then Ember's two numbers are applied to the sum. That detail matters. Ember judges one clip at a time, when that clip arrives. Four clips at 6,000 credits each would each pass a 20,000 limit, while together they spend 24,000. Applying the policy to the whole request makes the limit mean what Dad reads it to mean: the most this one click may spend without asking.

Two kinds of no

	Needs confirmation	Blocked
Caused by	A setting never priced, or a total above the limit	A total that would cut into the reserve, or Ember's own block (a vendor connection that is not configured or not reachable)
Who can lift it	Dad, by consenting	Nobody. No consent overrides it.
How consent arrives	`clip.confirm`, or a `max_credits` that covers a fully priced total	It cannot
In the studio	A checkbox with the reasons	A warning, and the button stays disabled

Note the condition on max_credits. It counts only when every clip in the request has a price. An unknown cannot be covered by a budget, because there is nothing to compare. The test makes the reserve's priority explicit too: with 501,000 credits left and a 4,848-credit clip, confirm: true still comes back blocked, with kept for Pippa's voice in the sentence.

409, and nothing is queued

generate() runs the plan inside the studio's intent lock and reads its spending before anything is written. A block becomes a 409 carrying the block's own sentence. A missing consent becomes a 409 that begins This clip needs confirmation before it is paid for and then lists the reasons. Both checks sit before create_intent, so a refused request leaves no batch, no task and no stored request id. The test asserts exactly that: after the refusal, the batch list is empty.

Why 409 and not 422? A 422 says the request itself is wrong, and Avatars uses it for exactly that: a set on a clip, too many references, an unknown generator. A consent refusal is different. The request is well formed; what it conflicts with is the state of the account and the policy. Send the same body again with consent added, and it goes through. Ember answers its own POST /jobs the same way, with a 409 coded confirmation_required and the plan attached. An image request never carries spending, so this branch is the clip workflow's alone.

The checkbox is the consent

The studio's review dialog turns the same fields into words. It says About 4,848 credits, leaving the balance after, or that no price has been observed for this setting yet. It shows the plan's notes and any block as a warning. When consent is needed and nothing blocks, it shows a checkbox whose label is the policy's own reasons followed by Spend the credits. The Generate clip button stays disabled while a block stands, or while consent is needed and the box is empty. Each new review starts with the box unchecked, so consent never carries over from an earlier preview. Pressing the button sends the reviewed request with clip.confirm set to the box. The same generate() sits behind Pippa's internal door, so a brain that asks for a clip meets the same 409 the screen does.

Then the worker says yes, once

When the worker later submits the clip, it sends confirm: true to Ember, with a comment saying consent was settled when the batch was accepted. Consent is asked once, at the place a person is looking at the number. The reserve is checked again, though. Ember plans every new POST /jobs against the balance it reads at that moment, and a block there comes back as a 422 that fails the task as Submission refused before anything is charged. The balance can move between review and submission, because my voice keeps talking in between.

Principle: Ask for consent where a person can see the number. Check the floor everywhere money moves.

Code

cwkEmber, backend/app/config.py: the default, the limit and the reserve (verbatim, lines 249-258)·python

    # Paid video through vendor APIs (coop todo #282), a system of its own
    # beside local video. Models are discovered; only the preferred default,
    # the spending policy and the limits are configuration.
    api_video_default_generator: str = "elevenlabs:veo-3.1-fast-generate-001"
    # A clip estimated above this many credits, or one whose price has never
    # been observed, needs the caller's confirmation before it is submitted.
    api_video_confirm_above_credits: int = Field(default=20000, ge=0)
    # ElevenLabs credits are one pool with Pippa's voice and there is no
    # top-up: a clip that would leave less than this is refused.
    api_video_reserve_credits: int = Field(default=500000, ge=0)

cwkAvatars, backend/studio.py: Ember's policy applied to the whole request (verbatim, lines 508-518)·python

        policy = catalog.get("policy") or {}
        ceiling, reserve, remaining = policy.get("confirm_above_credits"), policy.get("reserve_credits"), balance.get("credits_remaining")
        if blocked is None and remaining is not None and reserve is not None and remaining - known < reserve:
            blocked = f"{remaining:,} credits are left and {reserve:,} are kept for Pippa's voice; this request would cut into that reserve."
        reasons = []
        if unpriced:
            reasons.append(f"No price has been observed yet for {', '.join(sorted(set(unpriced)))}; the first run measures it.")
        if ceiling is not None and known > ceiling:
            reasons.append(f"The estimate of {known:,} credits is above the {ceiling:,}-credit limit for running without asking.")
        confirmed = bool(clip.confirm) or (clip.max_credits is not None and not unpriced and known <= clip.max_credits)
        spending = {"credits": None if unpriced else known, "known_credits": known, "unpriced": sorted(set(unpriced)), "requires_confirmation": bool(reasons), "confirmed": confirmed, "reasons": reasons, "blocked": blocked, "policy": policy, "credits_remaining": remaining, "credits_after": remaining - known if remaining is not None else None}

cwkAvatars, backend/studio.py: generate() answers 409 before anything is queued (verbatim, lines 555-561)·python

            spending = plan.get("spending")
            if spending:
                # Nothing is queued without the consent Ember's policy asks for.
                if spending["blocked"]:
                    raise StudioError(spending["blocked"], 409)
                if spending["requires_confirmation"] and not spending["confirmed"]:
                    raise StudioError("This clip needs confirmation before it is paid for. " + " ".join(spending["reasons"]), 409)

Exercise

Take an endpoint in your own software that spends money on a person's behalf. Give its plan step a spending object with two separate verdicts: requires_confirmation (with reasons a person can read) and blocked (a hard floor no consent overrides). Apply both to the total of the whole request, not to each unit. Make the submit endpoint answer 409 with the reason before it writes anything, and accept a confirm flag or a budget that covers a fully priced total. Write one test where confirm is true and the request is still blocked.

Hint

Keep the floor's number in the service that pays, and read it from there. A budget field is only safe when every unit has a price, so treat an unknown price as needing a person. Check that a refused request leaves no row behind, including the idempotency key, or the corrected retry will collide with a request that never happened.

Three numbers, all of them Ember's

The plan adds up the whole request

Two kinds of no

409, and nothing is queued

The checkbox is the consent

Then the worker says yes, once

Code

External links

Exercise

Progress

Comments 0