Black Forest Labs检查中

FLUX 3 / Text to Image

flux-3-text-to-image

文生图输出: 图像输入: 文本

正在加载价格…

官方原价 · 未验证

在 Playground 中试用获取 API Key

参数

必填

promptprompt: string

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

resolutionresolution: string

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

常用参数

aspectRatioaspectRatio: string

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

高级参数 (2)

groundinggrounding: boolean

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

safetyTolerancesafetyTolerance: integer

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 发送相同内容。

预计费用

正在加载价格…

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

模型能力

Generate images from a text prompt.

Resolution-based pricing · up to 4K

输入参数

仅列出此模型接受的字段。必填字段必须提供。

字段	类型	必填	默认值	可选值与约束
`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

限制与行为

仅支持异步：先提交任务，再轮询结果。
prompt: 1–20000 chars
safetyTolerance: 0–4

端点

所有模型共用一个异步任务 API，通过 slug 选择此模型。

提交

POST https://api.hermes-ai.net/api/v1/jobs

{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k"
  }
}

然后轮询 GET /api/v1/jobs/{id} 直到状态为终态。

身份验证

提交需要带 jobs:create 权限的 API Key，轮询需要 jobs:read。

请求头	值	说明
`Authorization`	`Bearer <API key>`	也可以通过 x-api-key 发送密钥。
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	必填。仅在重试完全相同的请求时复用。

请求体

字段	类型	必填	说明
`model`	`string`	必填	目录中的模型 slug。
`input`	`object`	必填	模型输入 schema 中的字段。
`expectedPriceMicros`	`integer`	可选	你向用户展示的价格。不一致时在扣费前返回 409 PRICE_CHANGED。

input 字段

未知字段会被拒绝并返回 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

响应

新任务返回 202，Idempotency-Key 重放命中时返回 200。GET /api/v1/jobs/{id} 返回相同结构（不含 replayed）。

字段	类型	说明
`id`	`string`	Hermes AI 任务 ID，用于轮询。
`model`	`string`	模型 slug。
`status`	`string`	参见任务状态。
`errorCode`	`string \| null`	任务失败或需要核对时设置。
`priceMicros`	`integer`	接收时锁定的报价，美元微单位。
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 时间戳。
`assets[]`	`array`	{ id, type, url?, text? }。url 为同源 /api/v1/results/<uuid> 链接。
`replayed`	`boolean`	仅提交时返回。幂等重试命中时为 true。

任务状态

状态	终态	含义
`queued`	否	已接收，等待执行。
`submitting`	否	正在提交给模型提供方。
`running`	否	模型生成中。
`succeeded`	是	已完成，结果位于 assets。
`failed`	是	未产生结果，预留额度已释放。
`reconciliation_required`	是	结果正在核实。请保留任务 ID，不要自动重新提交。

错误

错误响应体为 { code, error }，请根据 code 处理。

HTTP	代码	含义与处理方式
`401`	`AUTH_REQUIRED`	缺少或无效的 API Key 或会话。
`403`	`INSUFFICIENT_SCOPE`	API Key 缺少此端点所需的权限。
`403`	`PERMISSION_DENIED`	此凭据无权执行该操作。
`429`	`API_KEY_RATE_LIMITED`	已达到 API Key 的频率限制，请遵循 Retry-After。
`429`	`API_KEY_USAGE_EXCEEDED`	API Key 已达到使用上限，请创建新密钥。
`400`	`INVALID_REQUEST`	请求体不是 JSON 对象，或缺少必需值。
`400`	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key 必须是 1–128 个可打印 ASCII 字符。
`400`	`INVALID_MODEL_INPUT`	input 与模型 schema 不匹配（未知字段、缺少必填字段或值无效）。
`400 / 413`	`INPUT_TOO_LARGE`	请求体超过 256 KB。请先上传媒体并发送媒体引用。
`404`	`REQUEST_NOT_FOUND`	No chat request with this ID belongs to your account.
`404`	`MODEL_NOT_FOUND`	没有此 slug 对应的模型。
`404`	`JOB_NOT_FOUND`	你的账户中没有此 ID 的任务。
`409`	`IDEMPOTENCY_CONFLICT`	此 Idempotency-Key 已用于不同的输入。新请求请使用新密钥。
`409`	`PRICE_CHANGED`	价格与 expectedPriceMicros 不一致。请重新获取价格并确认。
`409`	`MODEL_PRICE_UNAVAILABLE`	此模型尚未配置价格，暂不可运行。
`409`	`PAYMENT_REVIEW_REQUIRED`	退款后余额不足。请联系支持或补足余额后再提交任务。
`409`	`INSUFFICIENT_CREDITS`	可用额度不足以支付此任务。
`429`	`RATE_LIMITED`	每分钟提交次数过多，请稍后重试。
`429`	`CONCURRENCY_LIMITED`	未完成任务过多，请等待任务完成。
`503`	`EXECUTION_UNAVAILABLE`	此模型当前未配置执行能力。
`429`	`UPSTREAM_RATE_LIMITED`	The model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
`502`	`UPSTREAM_ERROR`	The model provider failed the chat request. Nothing was charged; retry later.
`503`	`PLATFORM_BUDGET_EXCEEDED`	此模型暂时不可用，请稍后重试。
`503`	`EXECUTION_TEMPORARILY_UNAVAILABLE`	执行暂时不可用，请使用相同的 Idempotency-Key 重试。
`503`	`AUTH_UNAVAILABLE`	身份验证暂时不可用，请稍后重试。
`503`	`API_UNAVAILABLE`	API 暂时不可用，请稍后重试。

完整 API 指南 · OpenAPI 3.1

Hermes AI 价格

正在加载价格…

官方原价

模型厂商标准 API 美元原价，未应用渠道折扣。计费单位和规格以官方来源为准。

尚未核实此模型的官方原价。

影响成本的因素

分辨率、时长和输出数量可能影响报价。提交前请查看价格表和试验场报价。

· 仅对成功任务扣费。失败任务释放预留额度；结果尚未确认的任务会保留额度，直到结果核实。
· 使用相同幂等密钥重试不会重复扣费。
· 发送 expectedPriceMicros：若展示后价格发生变化，任务会以 PRICE_CHANGED 被拒绝。

费用估算

请在试验场选择规格，查看本次任务报价。

// 账单

计费方式

任务使用预付额度。可在账单页面充值，付款确认后余额更新。

发生时机	影响
任务已接收	从余额中预留本次报价金额。
任务成功	最终金额仅扣除一次，未使用的预留金额将退回。
任务失败	预留额度退回可用余额。

结果尚未确认的任务会保留预留额度，直到结果核实。如需帮助，请保留任务 ID 并联系支持。

付款退款会同步更新余额，并显示在账单页面的交易记录中。

最小请求

仅包含必填字段，由此模型的 schema 生成。请在环境变量中设置 HERMES_API_KEY。

# 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"

包含默认值

相同请求，并写出每个可选参数的默认值，便于调整。

# 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",
    "aspectRatio": "1:1",
    "grounding": true,
    "safetyTolerance": 2
  }
}'

# 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"