calesthio/generative-media-skills/bria-fibo-image

Bria FIBO image generation

Use Bria's first-party hosted v2 API unless the user explicitly asks for local weights. Keep local-weight licensing separate from hosted-API terms. Never route a first-party request through fal.ai, Replicate, or another gateway.

Evidence vocabulary

Use these labels when presenting material facts:

• Documented fact - stated by a cited first-party API schema, model card, paper, price page, or legal document.
• Provider claim - Bria's performance, training-data, safety, rights, compliance, or indemnity representation; do not restate it as independently verified fact.
• Operational heuristic - this skill's conservative recommendation, not a Bria limit or guarantee.
• Unknown - not established in the reviewed public first-party material. Ask Bria or inspect the user's executed agreement before relying on it.

Volatile facts and sources in this skill were checked 2026-07-10. Recheck schemas, pricing, plan limits, model cards, and governing terms before production or procurement decisions.

Start with a decision record

Before writing code or submitting work, capture:

1. Intent: generate, inspire from one reference, refine a saved structured prompt, or recreate from structured prompt plus seed.
2. Delivery: hosted Standard, hosted Lite, or local/on-prem evaluation.
3. Inputs: prompt, one reference image, saved structured_prompt, seed, and rights/consent provenance.
4. Output: aspect ratio, png or jpeg, Standard-only 1MP or 4MP, quantity, deadline, and acceptance criteria.
5. Governance: account/plan, permitted use, personal/confidential data classification, geography, retention requirement, and current agreement/DPA.
6. Spend: free-quota consumption or expected charge, maximum calls, maximum USD, and the person approving submission.

If rights, consent, or data classification are unclear, keep the work offline and ask. A public image URL is not evidence of permission.

Choose the exact route

Documented fact (v2 OpenAPI): base URL is https://engine.prod.bria-api.com/v2; authentication is the api_token request header. Bria's LLM documentation also asks agent clients to send User-Agent: BriaPlatform/APIdocs/LLMsAgent, although that requirement is not represented in the endpoint OpenAPI. Include it.

Provider claim: Standard is positioned for maximum interpretation quality; FIBO Lite is positioned for speed and lower cost. The FIBO Lite model card calls it a distilled few-step variant with a quality tradeoff. Benchmark the user's own prompt set before choosing production defaults.

Privacy consequence: Standard documentation says Gemini 2.5 Flash participates in prompt/image-to-JSON translation. The reviewed public pages do not establish the exact hosted data path, Google subprocessors/terms, region, retention, or whether zero-data-retention applies. Do not send sensitive, regulated, personal, or confidential inputs until the executed contract/DPA and architecture answer those questions. Lite's hosted route still sends data to Bria; "local/on-prem" requires a separately licensed deployment.

Current request contract

For the two image-generation routes, provide exactly one of these mutually exclusive combinations:

• prompt
• images (array, at most one item)
• images plus prompt
• structured_prompt
• structured_prompt plus prompt

For the two structured-prompt routes, current first-party schemas allow prompt, images, images plus prompt, or structured_prompt plus a refinement prompt; they do not allow structured_prompt alone. Enforce the selected route's schema rather than flattening the four endpoints into one contract.

For recreation or refinement, supply the saved seed with the saved structured prompt. structured_prompt is a string containing JSON, not a nested request object. Validate that it parses to a JSON object, but preserve the exact returned string as provenance.

Common documented image-generation fields:

• model_version: current enum is only FIBO. Send it to avoid silently omitting the field, but note that it does not pin an immutable backend revision.
• aspect_ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, or 16:9.
• seed: integer; the public OpenAPI gives no min/max. Do not invent a range.
• sync: defaults to false; use asynchronous operation for production.
• webhook_url: optional HTTPS callback for async work.
• output_type: png or jpeg; default png.
• ip_signal: default false; set true when IP warnings are useful to the workflow.
• prompt_content_moderation, visual_input_content_moderation, visual_output_content_moderation: current schema defaults to true. This skill always sends true and does not expose a disable switch.

Standard image-only fields:

• resolution: 1MP or 4MP, default 1MP. Bria says 4MP adds about 30 seconds; treat latency as a provider estimate.
• steps_num: integer 35-50, default 50.
• negative_prompt: optional string.

The current Lite image schema does not accept those three Standard-only fields. The current structured-prompt routes do not accept image-output fields. Reject unknown fields locally instead of hoping the service ignores them.

The OpenAPI accepts an image as a public URL or raw base64 without a data:image/...;base64, prefix and lists JPEG/JPG/PNG/WEBP. It documents no FIBO-specific byte, pixel, URL-fetch, animation, metadata, or decompression limits. A client-side cap is an operational heuristic, not a provider limit.

Compose controllable inputs

For initial text generation, make the prompt an auditable creative specification:

Purpose: ecommerce hero image for a ceramic pour-over set.
Subject: one matte cobalt dripper and matching carafe; accurate circular rim; no people.
Composition: centered three-quarter view, object fills 65% of frame, clear negative space at upper right.
Environment: warm gray seamless studio sweep.
Lighting: large softbox camera-left, gentle rim light, grounded soft shadow.
Camera: eye-level, 70 mm product-photography perspective, all product edges sharp.
Palette/material: cobalt #164B8C ceramic, neutral background, physically plausible glaze.
Text: none. Logos/brands: none.
Acceptance: one product set, no duplicate handles, no floating parts, no clipped silhouette.

For typography, put exact visible characters in quotes and repeat them in acceptance criteria. Generated text still needs human proofreading.

For a reference image:

• confirm the user owns or is licensed to submit it, including privacy/publicity permission for people;
• use one image only; strip unnecessary EXIF/GPS when policy permits, while preserving an untouched source separately;
• say which attributes may transfer (palette, lighting, broad composition) and which must not (identity, logo, distinctive protected character, watermark);
• do not describe "inspire" as copyright clearance or guaranteed non-similarity.

For iteration, save the returned structured prompt and seed. Ask for one isolated change, such as "change only the camera angle to a low three-quarter view; preserve subject count, palette, lighting, and layout." Diff the parsed JSON for review, but retain the original byte-for-byte string too. Provider claim: Bria describes structured prompt plus seed as deterministic/exact recreation and isolated refinement. Operational heuristic: treat it as repeatability intent, not bitwise identity, because the hosted route exposes no immutable model revision; measure perceptual/semantic drift in your own regression set.

Approval and cost policy

Preparing prompts, payloads, dry runs, validators, or local test fixtures is allowed. Any hosted generation or structured-prompt submission consumes quota and may incur fees.

Before a live request, require all four:

1. SEND_BRIA_REQUEST=1
2. APPROVE_BRIA_PAID_CALL=YES (also required for free-trial quota)
3. a numeric BRIA_MAX_COST_USD at least as large as the dated per-call estimate
4. BRIA_APPROVED_REQUEST_SHA256 copied from the reviewed dry run, binding approval to the exact route, payload/reference bytes, output-host allowlist, controlled output directory, cost, ceiling, and client job key

Also state route, call count, estimated maximum, and whether a retry could create a second billable job. Do not perform speculative variants. Do not treat a failed client connection as proof that Bria created no job.

Dated price-page fact (2026-07-10): Development lists Fibo at $0.03/image, Fibo Lite at $0.02/image, and Fibo Structured Prompt at $0.02/call; Business and Enterprise are custom. The page also advertises 100 free generations. Taxes, credits, negotiated rates, failed-job billing, 4MP treatment, and structured-prompt Lite pricing are not fully resolved by the public schema/page; the account console and executed agreement control.

The example blocks a live 4MP Standard call or Lite structured-prompt call until BRIA_ESTIMATED_CALL_USD is set from the live account/contract. This operator-supplied estimate then must fit under BRIA_MAX_COST_USD; it is not presented as a public Bria price.

There is a public rate-limit conflict: the API overview lists Free Trial 10, Starter 60, and Pro/Enterprise 1000 requests/minute per endpoint, while the price comparison shows 10, 60, and 150 actions/minute plus custom enterprise throughput. Do not hard-code either as entitlement. Read response headers if present, obey 429, and confirm the account's live limits.

Complete hosted example: dry-run first

This single-file Python 3.11+ client uses only the standard library for API calls and Pillow for local image validation (python -m pip install Pillow). It supports all four first-party routes, prompt/reference/refine inputs, asynchronous polling, strict URL policies, bounded reads, atomic writes, and a provenance manifest. It never sends by default.

Copy it to bria_fibo.py:

from __future__ import annotations
import base64
import hashlib
import ipaddress
import json
import math
import os
import random
import socket
import tempfile
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from pathlib import Path
from typing import Any
from urllib.error import HTTPError, URLError
from urllib.parse import urlsplit
from urllib.request import HTTPRedirectHandler, Request, build_opener
BASE = "https://engine.prod.bria-api.com/v2"
API_HOST = "engine.prod.bria-api.com"
USER_AGENT = "BriaPlatform/APIdocs/LLMsAgent"
ROUTES: dict[str, float | None] = {
    "/image/generate": 0.03,
    "/image/generate/lite": 0.02,
    "/structured_prompt/generate": 0.02,
    "/structured_prompt/generate/lite": None,  # public price page is not explicit
}
RATIOS = {"1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9"}
MAX_JSON_BYTES = 16 * 1024 * 1024       # client heuristic, not a Bria limit
MAX_INPUT_BYTES = 12 * 1024 * 1024      # client heuristic, not a FIBO limit
MAX_OUTPUT_BYTES = 64 * 1024 * 1024     # client heuristic
MAX_PIXELS = 40_000_000                  # client heuristic
POLL_TIMEOUT_S = 600