跳到主要内容

Black Forest LabsImage model检查中

FLUX 3 API

模型 IDflux-3-text-to-image

FLUX 3 Image and FLUX 3 Image Klein generate images from text and support reference-based editing.

  • 文生图
  • 图生图
  • Up to 10 input images
  • 1.5K, 2K or 4K output
  • 格式选项

在 Playground 中运行 FLUX 3

The form is the request body: every field shows its key. Sign in to run it; a run is billed like an API task.

参数

模型
model

FLUX 3文生图flux-3-text-to-image

必填
input.prompt

Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits. 1–20000 chars

input.resolution

Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP.

常用参数
input.aspectRatio

Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image.

高级参数 (2)
input.grounding

Allow web or image search before generation. On by default.

input.safetyTolerance

Moderation tolerance, 0 strictest to 4, default 2. 0–4

预估费用
正在加载价格…

任务接收时预留额度,仅成功后扣费。失败任务释放预留额度;结果未确认时会保留额度,直到核实。

请求预览

{"model": "flux-3-text-to-image","input": {"aspectRatio": "1:1","resolution": "1k","grounding": true,"safetyTolerance": 2}}

网页 Playground 使用你的登录会话发送此请求体。在代码中请使用 API Key 发送相同内容。

结果

运行请求后,结果会显示在这里,并附上状态和费用。

FLUX 3 价格

各可用版本和规格的价格以美元显示,计费单位随费率注明;只有找到可匹配的官方标价时才显示参考价格。

正在加载价格…
  • Charged only on success仅对成功任务扣费。失败任务释放预留额度;结果尚未确认的任务会保留额度,直到结果核实。
  • Safe retries使用相同幂等密钥重试不会重复扣费。
  • Price changes发送 expectedPriceMicros:若展示后价格发生变化,任务会以 PRICE_CHANGED 被拒绝。

对比 FLUX 3 各版本

每个变体都有独立的模型 ID 和输入参数。请先选择任务和版本;变体存在差异时会显示额外字段。

  • 文生图默认值

    flux-3-text-to-image

    文生图; 文本; 768sq, 1K, 1.5K, 2K, 4K; 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21

    grounding
  • 图生图

    flux-3-image-to-image

    图生图; 文本, 图像; 768sq, 1K, 1.5K, 2K, 4K; 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21

    grounding
  • Klein text to image

    flux-3-klein-text-to-image

    文生图; 文本; 768sq, 1K, 1.5K, 2K, 4K; 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21

    seedstepsoutputFormat
  • Klein image to image

    flux-3-klein-image-to-image

    图生图; 文本, 图像; 768sq, 1K, 1.5K, 2K, 4K; 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21

    seedstepsoutputFormat

FLUX 3 能做什么

Black Forest Labs lists FLUX 3 Image and Image Klein as distinct image models. The manufacturer describes Klein as an open-weights member of the family for generation and multi-reference editing; its API or self-hosting terms should be checked separately.

The Hermes catalog groups standard and Klein text-to-image and image-to-image variants on this page. Their schemas list output tiers from 768sq through 4k; edit variants accept up to ten reference images. The standard variants also list a grounding option. Check the selected variant's status and price before making a request.

Black Forest Labs also describes bounding-box editing for its FLUX 3 Image product. Those controls are not listed in these Hermes request schemas; consult the selected variant's parameters rather than assuming every manufacturer feature is exposed here.

能力

  • 格式选项

    请求参数列出了这些格式;具体可用性和结果交付取决于所选变体。

    JPEG · PNG

    outputFormat

    版本: Klein text to image, Klein image to image

  • 1.5K, 2K or 4K output

    Pick the output resolution: 768sq, 1K, 1.5K, 2K or 4K.

    resolution

    Every variant

  • 15 aspect ratios

    21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2 or 9:21.

    aspectRatio

    Every variant

  • Up to 10 input images

    Send up to 10 images in one request as HTTPS URLs or uploaded media references.

    imageUrls

    版本: 图生图, Klein image to image

  • 随机种子

    Accepts a seed value.

    seed

    版本: Klein text to image, Klein image to image

使用场景

  1. Create image concepts

    Describe a scene or visual brief and select a resolution and aspect ratio.

  2. Edit from references

    Supply reference images and a prompt that states what should change.

  3. Compare model variants

    Try standard or Klein when each is available, using the same prompt and output requirements.

用代码调用 FLUX 3

Every image, video and music model uses the same asynchronous job API: submit a task, then poll for the result.

  1. 1

    创建 API Key

    In the dashboard, with the jobs:create and jobs:read scopes. API 密钥
  2. 2

    提交任务

    POST /api/v1/jobs with the model ID and an input object. The response is 202 with a task ID.
  3. 3

    Poll for the result

    GET /api/v1/jobs/{id} until the status is succeeded, then download the output URLs.

最小请求

Required fields only, generated from the schema of 文生图. Set HERMES_API_KEY in your environment.

模型 ID
flux-3-text-to-image
端点
https://api.hermes-ai.net/api/v1/jobs
Full task API reference
# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

输入参数

Fields of 文生图 (flux-3-text-to-image). 未知字段会被拒绝并返回 INVALID_MODEL_INPUT。

字段类型必填默认值可选值与约束
prompt
string必填—

Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits.

1–20000 chars

aspectRatio
string可选"1:1"

Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image.

可选值: "auto", "21:9", "2:1", "16:9", "3:2", "7:5", "4:3", "5:4", "1:1", "4:5", "3:4", "5:7", "2:3", "9:16", "1:2", "9:21"

resolution
string必填"1k"

Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP.

可选值: "768sq", "1k", "1.5k", "2k", "4k"

grounding
boolean可选true

Allow web or image search before generation. On by default.

safetyTolerance
integer可选2

Moderation tolerance, 0 strictest to 4, default 2.

0–4

Headers, response, task statuses and errors
请求头值说明
AuthorizationBearer <API key>也可以通过 x-api-key 发送密钥。
Content-Typeapplication/json
Idempotency-Key<unique string ≤128>必填。仅在重试完全相同的请求时复用。
字段类型说明
idstringHermes AI 任务 ID,用于轮询。
modelstring模型 slug。
statusstring参见任务状态。
errorCodestring | null任务失败或需要核对时设置。
priceMicrosinteger接收时锁定的报价,美元微单位。
currency"USD"
createdAt / updatedAtstringISO 8601 时间戳。
assets[]array{ id, type, url?, text? }。url 为同源 /api/v1/results/<uuid> 链接。
replayedboolean仅提交时返回。幂等重试命中时为 true。
状态终态含义
queued否已接收,等待执行。
submitting否正在提交给模型提供方。
running否模型生成中。
succeeded是已完成,结果位于 assets。
failed是未产生结果,预留额度已释放。
reconciliation_required是结果正在核实。请保留任务 ID,不要自动重新提交。
HTTP代码含义与处理方式
401AUTH_REQUIRED缺少或无效的 API Key 或会话。
403INSUFFICIENT_SCOPEAPI Key 缺少此端点所需的权限。
403PERMISSION_DENIED此凭据无权执行该操作。
429API_KEY_RATE_LIMITED已达到 API Key 的频率限制,请遵循 Retry-After。
429API_KEY_USAGE_EXCEEDEDAPI Key 已达到使用上限,请创建新密钥。
400INVALID_REQUEST请求体不是 JSON 对象,或缺少必需值。
400INVALID_IDEMPOTENCY_KEYIdempotency-Key 必须是 1–128 个可打印 ASCII 字符。
400INVALID_MODEL_INPUTinput 与模型 schema 不匹配(未知字段、缺少必填字段或值无效)。
400 / 413INPUT_TOO_LARGE请求体超过 256 KB。请先上传媒体并发送媒体引用。
404REQUEST_NOT_FOUNDNo chat request with this ID belongs to your account.
404MODEL_NOT_FOUND没有此 slug 对应的模型。
404JOB_NOT_FOUND你的账户中没有此 ID 的任务。
409IDEMPOTENCY_CONFLICT此 Idempotency-Key 已用于不同的输入。新请求请使用新密钥。
409PRICE_CHANGED价格与 expectedPriceMicros 不一致。请重新获取价格并确认。
409MODEL_PRICE_UNAVAILABLE此模型尚未配置价格,暂不可运行。
409PAYMENT_REVIEW_REQUIRED退款后余额不足。请联系支持或补足余额后再提交任务。
409INSUFFICIENT_CREDITS可用额度不足以支付此任务。
429RATE_LIMITED每分钟提交次数过多,请稍后重试。
429EXPORT_RATE_LIMITED本分钟内导出 CSV 次数过多,请按 Retry-After 等待后重试。
429CONCURRENCY_LIMITED未完成任务过多,请等待任务完成。
503EXECUTION_UNAVAILABLE此模型当前未配置执行能力。
429UPSTREAM_RATE_LIMITEDThe model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
502UPSTREAM_ERRORThe model provider failed the chat request. Nothing was charged; retry later.
503PLATFORM_BUDGET_EXCEEDED此模型暂时不可用,请稍后重试。
503EXECUTION_TEMPORARILY_UNAVAILABLE执行暂时不可用,请使用相同的 Idempotency-Key 重试。
503AUTH_UNAVAILABLE身份验证暂时不可用,请稍后重试。
503API_UNAVAILABLEAPI 暂时不可用,请稍后重试。

FLUX 3 API 常见问题

Answers built from the model's schema and the Hermes AI API contract.

Does this page cover FLUX 3 Video?

No. This family page covers image variants. FLUX 3 Video has separate text-to-video, image-to-video and continuation variants.

Can I use the manufacturer's bounding-box editor here?

The manufacturer describes bounding-box controls on its product page, but they are not exposed in the current Hermes schemas for these variants.

What can the FLUX 3 API do?

Black Forest Labs 的 FLUX 3 支持文生图 和 图生图。目录列有4 variants, each,每个变体都有自己的模型 ID 和输入参数。提交请求前请先确认当前可用状态。

Which durations, resolutions and aspect ratios does FLUX 3 support?

Across its variants, FLUX 3 supports 768sq, 1K, 1.5K, 2K 和 4K resolution 和 aspect ratios 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2 和 9:21. Each variant accepts its own subset; the variants table on this page lists them.

What input does FLUX 3 accept?

A text prompt of up to 20,000 characters, plus 图像 input (up to 10 images per request). Media fields take a public HTTPS URL or a media:<uuid> reference returned by POST /api/v1/media, so local files can be uploaded first. 未知字段会被拒绝并返回 INVALID_MODEL_INPUT。

How is FLUX 3 priced and billed?

You pay per successful task from prepaid credits, with no subscription. The price depends on the variant and the specification you choose, such as resolution or duration; see the pricing table on this page or the pricing page. Credits are reserved when a task is accepted and charged only when it succeeds; a failed task returns the reservation to your balance.

Which FLUX 3 variant should I choose?

For 文生图, 文生图 和 Klein text to image differ in fields: 文生图 adds grounding; Klein text to image adds seed, steps, outputFormat; for 图生图, 图生图 和 Klein image to image differ in fields: 图生图 adds grounding; Klein image to image adds seed, steps, outputFormat. Pick the task first, then compare the tiers in the variants table.

How do I call the FLUX 3 API from code?

Send POST https://api.hermes-ai.net/api/v1/jobs with the variant's model ID and an input object, then poll GET /api/v1/jobs/{id} until the status is succeeded or failed. The API section has cURL, JavaScript and Python examples generated from the schema.

Can I try FLUX 3 without writing code?

Yes. Sign in and use the playground on this page: it sends the same request as the API with your session and charges the same price. Code needs an API key from the dashboard.

What happens when a task fails or I hit a rate limit?

A failed task is not charged and its reserved credits are returned. Too many submissions per minute return 429 RATE_LIMITED, and too many unfinished tasks return 429 CONCURRENCY_LIMITED; retry later or wait for a task to finish.