此文暂无当前语言版本,显示原文。
博客

Guide

FIBO 2.0 Developer Guide: Capabilities, Pricing, and Integration

Choosing between text-to-image and image-to-image routes, wiring the parameters, and budgeting at $0.0572 per image

Nov 16, 2026 10 min read
Flat abstract cover art of slow liquid forms folding over an ink-dark base, with celadon and slate currents.
本页内容

What FIBO 2.0 Offers and How to Choose a Route

FIBO 2.0 is an image model family exposed on HiAPI through two distinct routes, and the first design decision you make is which one your task actually needs.

The text-to-image route (fibo-2.0-text-to-image) turns a written prompt into an image. It is the right choice when no source image exists yet: concept art, marketing visuals, placeholder assets, or any case where the description is the whole specification. It also accepts an optional image_url reference or a style preset when you want to steer the photographic look, but not both at once (more on that below).

The image-to-image route (fibo-2.0-image-to-image) takes one to four input images plus an instruction describing what to change. Reach for this when you already have pixels you want to preserve — retouching a product shot, restyling an existing asset, or composing a scene where the first image is the subject and the following images are references. It additionally supports mask_url for localized edits.

A practical rule: if your request can be expressed as "make me a picture of X," use text-to-image. If it can only be expressed as "change Y in this picture," use image-to-image. Both routes are billed the same way — per image, single tier — so the decision is about fidelity to an existing source, not cost.

Because both routes share the same aspect ratio vocabulary and seed semantics, switching between them mid-project is cheap in engineering terms: your validation layer and your reproducibility logging stay mostly identical.

Two routes, one output: text-to-image and image-to-image converge on the same final image.

Text-to-Image: Prompt, Aspect Ratio, Seed, and the Reference-or-Style Rule

The text-to-image surface is small, which makes it quick to wire up but also means each parameter carries real weight.

prompt

Required, a string with minLength=1 and maxLength=10000. This is the only mandatory field on the route. Treat the upper bound as generous but not infinite — long prompts do not automatically produce better images, so keep the operative instruction near the front.

aspect_ratio

A string enum with 20 values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 16:10, 10:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3, 4:1, 1:4, 5:1, 1:5. The default is 1:1. Output lands at roughly one megapixel regardless of ratio, so the choice changes shape, not detail budget. There is no separate resolution parameter — do not invent one in your client code.

seed

An integer from 0 to 2147483647, defaulting to 5555. The same seed with the same inputs reproduces the same image. This is your only reproducibility lever, so log the seed you sent alongside every stored output. Note that the default is a fixed value, which means two identical calls with no explicit seed will return the same image rather than a fresh sample — if you want variation across a batch, vary the seed yourself.

The reference-or-style rule

This is the trap that breaks the most requests. image_url and style are mutually exclusive. image_url is a public URL used as a visual reference for the prompt's scene; style accepts exactly one of Kodak Film, Hard Flash, Hazy Dreamy, or Rough Realism. Send both and the request is invalid. Pick one: a reference image to anchor content, or a style preset to anchor look.

Also remember that image_url must be publicly reachable by the service, not a signed URL that expires in sixty seconds.

Prompt is required; many ratios collapse to roughly one megapixel; seed fixes reproducibility; image_url and style are mutually exclusive.

Image-to-Image: Multi-Image Instructions and Masked Edits

The image-to-image route inverts the required fields: instead of a prompt, you supply image_urls and an instruction.

image_urls

A required array with minItems=1 and maxItems=4. The ordering is meaningful: the first image is the one being edited, and the remaining up to three are references. Address them in the instruction as <image_1>, <image_2>, and so on, in exactly that order. A typical instruction might read "keep the product from <image_1> but relight it to match the mood of <image_2>." Getting the index-to-URL mapping wrong is the most common quality bug on this route, so build your index tokens programmatically from the array rather than hardcoding them.

instruction

Required, minLength=1, maxLength=10000. Describe what to change, not what to keep from scratch — the source image already carries the composition.

mask_url

Optional and deliberately restricted: it applies to single-image edits only, meaning image_urls must contain exactly one image. The mask must match the source image's size. White marks the region to edit, black is preserved. If you send a mask with two or more images, or with a mismatched size, expect a validation failure rather than a silent fallback.

aspect_ratio on this route

Here the semantics differ from text-to-image. If you omit aspect_ratio, the output follows the first input image's ratio. A single-image edit always keeps that image's ratio, even if you pass a value. Passing aspect_ratio only becomes meaningful in multi-image requests where you want a canvas different from the lead image. The enum accepts the same 20 values, still at roughly one megapixel.

seed

Same contract as text-to-image: 0 to 2147483647, default 5555, same seed and inputs reproduce the same result.

A good mental model: this route is a directed edit, not a re-render. Keep instructions surgical and use the mask when precision matters more than global consistency.

Inputs converge into one instruction; the mask overlay is a separate channel — and only for a single image.

Parameter Reference and Common Validation Traps

Validate on the client before the request leaves your process — a rejected call still costs you latency and, if you retry blindly, budget.

Shared across both routes

  • seed: integer, 0–2147483647, default 5555.
  • aspect_ratio: string, 20-value enum (1:1 through 1:5 as listed), default 1:1 on text-to-image; on image-to-image it defaults to the first image's ratio and is ignored on single-image edits.

Text-to-image

  • prompt: required, string, 1–10000 characters.
  • image_url: optional, string, minLength=1, must be public.
  • style: optional, enum Kodak Film / Hard Flash / Hazy Dreamy / Rough Realism.
  • Exclusion: image_url XOR style.

Image-to-image

  • image_urls: required array, 1–4 public URLs, first is the edit target.
  • instruction: required, string, 1–10000 characters.
  • mask_url: optional string, minLength=1, only when image_urls has exactly one entry, and must match that image's dimensions.

The traps worth encoding as assertions

First, the image_url/style pair — reject both-present at the call site rather than relying on an API error. Second, mask-plus-multi-image — assert len(image_urls) == 1 whenever mask_url is set. Third, mask size matching — you cannot check this server-side without downloading the image, so fetch dimensions during ingestion and store them alongside the URL. Fourth, index tokens in instruction that exceed the number of URLs supplied; a <image_3> reference with two images is meaningless. Fifth, non-HTTPS or expiring URLs: pre-flight them with a HEAD request.

One more habit: keep the enum list in a single shared constant imported by both routes. The two routes use the identical ratio set, and duplicating it is how drift starts.

Pricing Model and Cost Planning for Real Workloads

Both routes are billed per image at the official rate of $0.0572, on a single tier. There is no separate charge for the mask, the number of reference images, the seed, or the length of your instruction. A four-image reference request costs the same as a one-image edit, and a text-to-image call with a reference image costs the same as one without.

That flatness has a useful consequence: your cost model is simply calls multiplied by the per-image rate published on the pricing panel. It does not require a lookup table keyed on parameters.

Where budgets actually go sideways is retries. The cost that scales is the number of successful generations, not the complexity of any single one. Three plausible failure modes to design against:

  • Blind retry loops. If a request fails validation (mutually exclusive parameters, oversized mask, dead URL), retrying identical input fails identically. Validate first, then retry only on transport errors, with backoff and a cap.
  • Re-sampling for variation. Because the default seed is fixed, teams sometimes resubmit hoping for a different image. That is a paid call each time. If you are exploring, treat generations as deliberate samples and log which seed produced which output so you never pay to rediscover one you already have.
  • Regenerating instead of caching. Store outputs keyed on a hash of the normalized request — route, prompt or instruction, image URLs, mask URL, aspect ratio, seed. A cache hit costs nothing; a cache miss costs one image. For iterative UI work this is usually the largest single saving.

Batch sizing follows the same logic: run small pilot batches at a fixed seed to validate prompts, then expand seeds only once the prompt is settled. Since output is roughly one megapixel regardless of aspect ratio, there is no hidden cost reason to prefer one ratio over another — choose on design grounds.

Integration Checklist and Reproducibility Practices

Run this before every deploy, and keep the logging half of it permanently on.

Pre-flight checklist

  1. Route chosen deliberately: text-to-image when the prompt is the spec, image-to-image when the source pixels matter.
  2. Required fields present — prompt for text-to-image; image_urls and instruction for image-to-image.
  3. image_url and style not both set.
  4. mask_url, if present, on a single-image request with matching dimensions.
  5. Every URL is public, HTTPS, and does not expire; HEAD-check during ingestion.
  6. aspect_ratio set explicitly on text-to-image if the default 1:1 is not what your layout needs; left unset on single-image edits so the source ratio is inherited.
  7. Index tokens in instruction never exceed the number of URLs.
  8. Seed set explicitly and recorded in the response record.

Reproducibility practices

Persist a request record containing the route slug, the full normalized parameters, the seed, the timestamp, and the output location. Hash it for cache lookup. When a stakeholder asks for "that image again, slightly different," you replay the record with one changed field and a new seed, rather than reconstructing from memory.

Keep a fixture suite of a handful of prompts and seeds and re-run it whenever you upgrade your client — it catches enum drift and exclusion-rule regressions cheaply.

For the exact parameter schemas, check the text-to-image route and the image-to-image route pages, and confirm current per-image rates on the pricing panel before you size a budget.

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档