Files
ai/controllers/images_api.go
zooqueenandHanzo Dev 4cbf1f81a5 Paid lane: each call holds its worst case against the day, its org's share and its plan
A paid-lane call is seated once, by the balance gate (controllers.Seat), and
holds its estimate — prompt and completion ceiling at the most of list price
and cost, twice for fast mode, media at unit price — from admission until its
usage record settles it. The hold must fit PAID_LANE_DAILY, the paying org's
share of it (PAID_LANE_ORG_SHARE, default 0.25) and, for a plan-paid call, the
plan class's LimitGrant.Spend less the payer's holds in flight. A call that
does not fit is on the free lane: a chat for a third-party model is answered by
the free model, anything else only the paid lane serves is refused 429
paid_lane_full. Each org's settled spend per UTC day is kept in the store
(object.PaidDay), so a restart keeps the day. PAID_LANE_DAILY parses with
bounds; Inf and NaN close the lane.

Every ZAP handler asks the HTTP handlers' lane decision (paying via zapLane,
Jev in decide): a ZAP request holds no seat, so it never reaches a vendor that
spends Hanzo's money, with the switch on or off.

Race losers and video jobs settle the seat their request was admitted on; a
family is sent X-Hanzo-Spend only on a seat, capped at what it holds. A row an
org holds for itself is served off the paid lane while the switch is on, is
never handed to the free model and counts nothing against the day. With the
switch off no lane is named and a program past its plan's usage gets its 402,
as before. The test hook on the lane is gone; tests seat their requests.

Co-authored-by: Hanzo Dev <[email protected]>
2026-10-08 06:11:02 -07:00

247 lines
9.1 KiB
Go

// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package controllers
import (
"context"
"encoding/json"
"fmt"
"net/http"
"time"
"github.com/google/uuid"
iam "github.com/hanzoai/ai/internal/iam"
"github.com/hanzoai/ai/model"
"github.com/hanzoai/ai/object"
"github.com/hanzoai/ai/upstream"
)
// This file completes the OpenAI-compatible surface alongside chat and
// embeddings: the /v1/images/generations endpoint. It rides the SAME
// authentication, model-routing, provider-resolution, balance-reservation, and
// usage-recording machinery as ChatCompletions and Embeddings (see
// openai_api.go / embeddings_api.go) — one auth+routing policy, one billing
// ledger. The only image-specific piece is the execution:
// model.GenerateImageForModel dispatches to the correct upstream shape — the
// fal-hosted diffusion models (zen3-image* / fal-ai/*) via DO's asynchronous
// image client, and the synchronous OpenAI shape (Stable Diffusion 3.5 Large,
// dall-e, gpt-image) via client.Images.Generate — and the response is the
// OpenAI images JSON shape {"created":<ts>,"data":[{"url":…}|{"b64_json":…}]}.
// imagesGenerationsRequest is the OpenAI /v1/images/generations request body.
// Only model + prompt are required; the rest are optional and passed through.
type imagesGenerationsRequest struct {
Model string `json:"model"`
Prompt string `json:"prompt"`
N int `json:"n"`
Size string `json:"size"`
ResponseFormat string `json:"response_format"`
}
// ImagesGenerations implements POST /v1/images/generations (OpenAI-compatible).
//
// Body: {"model": "...", "prompt": "...", "n"?: int, "size"?: "1024x1024",
//
// "response_format"?: "url"|"b64_json"}
//
// It authenticates the caller, resolves the model to its upstream provider via
// the shared routing table (zen3-image* → do-ai fal diffusion), reserves the
// per-image budget, generates the image(s) through the do-ai async image
// client, records usage for billing, and returns the OpenAI images response.
// @Title ImagesGenerations
// @Tag OpenAI Compatible API
// @Description OpenAI compatible image generations API.
// @router /images/generations [post]
func (c *ApiController) ImagesGenerations() {
token, ok := c.bearerToken()
if !ok {
return
}
if isPublishableKey(token) {
c.rejectPublishableKey()
return
}
var req imagesGenerationsRequest
badReq := ""
if err := json.Unmarshal(c.Body(), &req); err != nil {
badReq = fmt.Sprintf("Failed to parse request: %s", parseProblem(err))
} else if req.Model == "" {
badReq = "images request requires a \"model\" field"
} else if req.Prompt == "" {
badReq = "images request requires a \"prompt\" field"
}
if badReq != "" {
// Authenticate before reporting the client error: an invalid credential is
// 401 regardless of body validity (never a probe-able 200/400).
if authErr := c.authenticate(token); authErr != nil {
c.ResponseAuthError(authErr)
return
}
c.ResponseErrorWithStatus(http.StatusBadRequest, badReq)
return
}
startTime := time.Now().UTC()
orgId := c.GetOrg()
provider, authUser, upstreamModel, isPremium, err := c.authResolveProvider(token, req.Model, orgId)
if err != nil {
c.ResponseAuthError(err)
return
}
if paying(c.Context(), provider) {
c.ResponseAuthError(laneOff(c.Context(), req.Model))
return
}
if provider.Category != "Model" {
c.ResponseError(fmt.Sprintf("Provider %s is not a model provider", provider.Name))
return
}
if upstreamModel != "" {
provider.SubType = upstreamModel
} else if req.Model != "" {
provider.SubType = req.Model
}
// Zen family: forward to the zen service, billed per image at the discovered
// price. zen owns the SKU→upstream mapping; ai authenticates, meters, forwards.
if provider.Type == "Zen" {
n := min(max(req.N, 1), 10)
c.serveZenMedia("images/generations", req.Model, c.Body(), n, orgId, authUser, isPremium, startTime)
return
}
// Clamp n to [1,10] BEFORE any cost math so imageCostCents/reserveBudget are
// never fed an unbounded n (mirrors the same clamp in doaiImageSubmit). This
// makes the money-safety explicit rather than relying on int overflow.
n := min(max(req.N, 1), 10)
// ── Balance reservation ────────────────────────────────────────────
// Reserve the exact per-image cost so concurrent image requests for one
// subject can't double-spend a balance the async debit hasn't applied yet.
// Settled with the ACTUAL produced-image cost on completion (fail-safe
// release deferred). Images are billed per image, so the reservation is the
// image cost, not a token estimate.
var hold *budgetHold
if authUser != nil {
ledger := c.billingOrg(authUser)
subject := authUser.PayerSubject(ledger)
var ok bool
if hold, ok = reserveFor(c.Context(), subject, imageCostCents(req.Model, n)); !ok {
c.ResponseAuthError(billingError("%s", object.InsufficientBalance(c.Host(), ledger, "image cost").Message))
return
}
}
defer hold.settle(0)
// Generate the image(s) via the do-ai async image client. The provider's
// resolved key (never logged) and base URL drive submit → poll → retrieve.
ctx, cancel := context.WithTimeout(context.Background(), 130*time.Second)
defer cancel()
upstreamURL := upstreamBase(provider)
if upstreamURL == "" {
c.ResponseError("No upstream endpoint configured for provider: " + provider.Name)
return
}
result, err := model.GenerateImageForModel(ctx, upstreamURL, provider.ClientSecret, model.ImageGenRequest{
UpstreamModel: provider.SubType,
Prompt: req.Prompt,
N: n,
Size: req.Size,
})
if err != nil {
c.recordImageUsage(authUser, provider, req.Model, isPremium, 0, "error", err.Error(), startTime)
c.ResponseError(fmt.Sprintf("Image generation failed: %s", err.Error()))
return
}
// Bill for the images produced, capped at the requested n. The reservation
// covered n; capping here guarantees the settle can never exceed the hold
// even if the upstream ever returned more images than requested — the user
// is never charged beyond what they asked for.
billedCount := min(len(result.Images), n)
hold.settle(imageCostCents(req.Model, billedCount))
c.recordImageUsage(authUser, provider, req.Model, isPremium, billedCount, "success", "", startTime)
c.jsonResponse(map[string]any{
"created": time.Now().Unix(),
"data": imageResponseData(result),
})
}
// imageResponseData projects the generated images into the OpenAI images data
// array: each element carries "url" or "b64_json" per what the upstream
// returned (fal returns url).
func imageResponseData(result *model.ImageGenResult) []map[string]string {
data := make([]map[string]string, 0, len(result.Images))
for _, im := range result.Images {
entry := map[string]string{}
if im.URL != "" {
entry["url"] = im.URL
}
if im.B64JSON != "" {
entry["b64_json"] = im.B64JSON
}
data = append(data, entry)
}
return data
}
// upstreamBase returns the provider's base URL for the async image API
// (the do-ai provider's ProviderUrl, e.g. https://inference.do-ai.run/v1). It
// reuses endpoint so provider URL handling lives in exactly one place; the async
// client appends /async-invoke itself, so the empty path yields the clean base
// with the provider's /v1 normalization applied.
func upstreamBase(provider *object.Provider) string {
base := upstream.Endpoint(provider, "")
// endpoint returns "<base>/" for the empty path; trim the trailing slash so
// the caller's join — "/async-invoke", "/videos" — is clean.
for len(base) > 0 && base[len(base)-1] == '/' {
base = base[:len(base)-1]
}
return base
}
// recordImageUsage records a single image-generation usage event for billing +
// observability, mirroring the embeddings/rerank recording. imageCount drives the
// per-image cost, so a generation that failed before any image came back bills nothing
// while still filing its row: recordUsage prices the outcome, it does not filter it.
func (c *ApiController) recordImageUsage(authUser *iam.User, provider *object.Provider, userModel string, isPremium bool, imageCount int, status, errMsg string, startTime time.Time) {
if authUser == nil {
return
}
rec := &usageRecord{
Owner: c.billingOrg(authUser),
Organization: authUser.Owner,
Model: userModel,
Provider: provider.Name,
Origin: provider.Origin(),
ImageCount: imageCount,
Currency: "USD",
Premium: isPremium,
Status: status,
ErrorMsg: errMsg,
ClientIP: c.Fiber().IP(),
RequestID: uuid.NewString(),
}
rec.bind(c.Context(), authUser)
recordUsage(rec)
recordTrace(c.Context(), rec, startTime)
}