Flux Kontext

@runapi.ai/flux-kontext — RunAPI.ai Flux Kontext 图像生成 通过 RunAPI.ai 构建 Node / TypeScript 集成，生成和转换图像。 设置 需要 Node 18+（全局 fetch）。 npm install @runapi.ai/flux-kontext 在环境中设置 API 密钥： #.env RUNAPI_API_KEY=runapi_xxx # 获取一个在 https://runapi.ai/api_keys 导入 { FluxKontextClient } from '@runapi.ai/flux-kontext'; // SDK 从环境中自动读取 RUNAPI_API_KEY。 const client = new FluxKontextClient(); 如果您以不同的方式管理密钥，请显式传递 { apiKey }。 baseUrl 默认为 https://runapi.ai；仅在本地开发时覆盖。 核心配方 — 文本到图像 const result = await client.textToImage.run({ model: 'flux-kontext-pro', prompt: 'A futuristic cityscape at night', aspect_ratio: '16:9', output_format: 'jpeg', }); const url = result.images[0].url; run() 创建任务，自动轮询，并仅在任务完成时解析 — images[0].url 在成功时填充。 在失败时抛出 TaskFailedError；在轮询超时时抛出 TaskTimeoutError。 对于脚本和短暂进程，请使用 run()。 对于请求处理程序，请分割它： const { id } = await client.textToImage.create({ model: 'flux-kontext-pro', prompt: '...', }); // 立即返回 202；稍后获取： const status = await client.textToImage.get(id); if (status.status === 'completed') { / ... / } 不要保持 Web 工作线程打开等待 run()。 分割 + webhook 是生产模式。 run() 默认每 2 秒轮询一次，最高 15 分钟。 根据需要调整： await client.textToImage.run(params, { maxWaitMs: 5 60_000, pollIntervalMs: 2_000 }); 如果 TaskTimeoutError 发生，任务仍在服务器端运行 — 使用 textToImage.get(id) 或通过 webhook 完成。 图像到图像 — 编辑源图像 将 input_image（单个 URL）与您的提示一起传递： await client.textToImage.run({ model: 'flux-kontext-max', prompt: 'Restyle as a 1970s film photograph', input_image: 'https://cdn.example.com/source.jpg', aspect_ratio: '4:3', }); 模型 model 用例 flux-kontext-pro 成本效益高的生产输出。 flux-kontext-max 更高保真度变体。 aspect_ratio 值：21:9、16:9、4:3、1:1、3:4、9:16。 output_format：jpeg / png。 每个模型的确切信用成本在 https://runapi.ai/pricing 和仪表板中显示 — 不要在应用程序代码中硬编码价格。 回调（webhook） 在 create()（或任何 run() 调用）上传递 callback_url，RunAPI 将最终有效载荷 POST 到您： await client.textToImage.create({ model: 'flux-kontext-pro', prompt: '...', callback_url: 'https://your.app/webhooks/runapi/flux-kontext', }); 有效载荷形状： { id: string; status: 'completed' | 'failed'; images?: { url: string; origin_url?: string }[]; error?: string } 在信任正文之前始终验证签名。 RunAPI 使用您的帐户的回调密钥（在 /accounts/callback_secret 中旋转）对每个回调进行签名。 头： X-Callback-Id — UUID，存储以使处理程序幂等 X-Callback-Timestamp — Unix 秒，拒绝如果 |now - ts| > 300 X-Callback-Signature — base64 HMAC-SHA256 在 ${id}.${ts}.${rawBody} 上使用 base64 解码的密钥 导入 crypto from 'node:crypto'; 函数 verify(raw: string, id: string, ts: string, sig: string, secret: string) { const key = Buffer.from(secret, 'base64'); const mac = crypto.createHmac('sha256', key) .update(${id}.${ts}.${raw}) .digest('base64'); 返回 crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig)); } 在 10 秒内回复 2xx；任何非 2xx 触发重试。 错误 所有错误都从 @runapi.ai/core 中重新导出。 始终 instanceof — 永远不要字符串匹配消息。 错误 状态 操作 AuthenticationError 401 中止；显示“重新连接您的 API 密钥” InsufficientCreditsError 402 提示用户在 runapi.ai/billing 中补充 ValidationError 400 / 422 修复参数；不要重试 RateLimitError 429 睡眠 err.retryAfterMs，然后重试 ServiceUnavailableError 503 / 455 重试带有退避；暂时的服务问题 TaskFailedError — 向用户显示 err.details；不要自动重试 TaskTimeoutError — 使用 textToImage.get(id) 重试 导入 { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/flux-kontext'; 尝试 { await client.textToImage.run({ model: 'flux-kontext-pro', prompt: '...', }); } catch (err) { 如果 (err instanceof InsufficientCreditsError) { / 显示补充 CTA / } else if (err instanceof TaskFailedError) { / 显示 err.details */ } else throw err; } 陷阱 model 在每个调用中都是必需的。 input_image 是一个单个 URL（字符串），不是一个数组 — 这是家族中唯一一个接受标量 URL 的端点。 enable_translation 默认为 true — 提示自动翻译为英语。 将其设置为 false 以保持原始提示。 callback_url 必须从公共互联网访问。 localhost / 127.0.0.1 URL 将永远不会触发 — 在本地开发时使用隧道（cloudflared、ngrok、tailscale funnel）。 深入探讨 包 README （fu