@runapi.ai/flux-kontext 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+# Flux Kontext API JavaScript SDK for RunAPI
+
+The flux kontext api JavaScript SDK is the language-specific package for Flux Kontext on RunAPI. Use this flux kontext api package for text-to-image, image-to-image, edit, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in JavaScript.
+
+This flux kontext api README is the JavaScript package guide inside the public `flux-kontext-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/flux-kontext; for API reference, use https://runapi.ai/docs#flux-kontext; for SDK docs, use https://runapi.ai/docs#sdk-flux-kontext.
+
+## Install
+
+```bash
+npm install @runapi.ai/flux-kontext
+```
+
+## Quick start
+
+```typescript
+import { FluxKontextClient } from '@runapi.ai/flux-kontext';
+
+const client = new FluxKontextClient();
+const task = await client.generations.create({
+  // Pass the Flux Kontext JSON request body from https://runapi.ai/docs#flux-kontext.
+});
+const status = await client.generations.get(task.id);
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion. In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+## Language notes
+
+Use the TypeScript types in `src/types.ts` and the resource classes under `src/resources` when building image applications. The available resources include generations. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/flux-kontext
+- SDK docs: https://runapi.ai/docs#sdk-flux-kontext
+- Product docs: https://runapi.ai/docs#flux-kontext
+- Pricing and rate limits: https://runapi.ai/models/flux-kontext/pro
+- Provider comparison: https://runapi.ai/providers/black-forest-labs
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/flux-kontext-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

package/dist/index.d.mts

@@ -0,0 +1,75 @@
+import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, ClientOptions } from '@runapi.ai/core';
+export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundError, RateLimitError, RunApiError, ServiceUnavailableError, TaskFailedError, TaskTimeoutError, TimeoutError, ValidationError } from '@runapi.ai/core';
+
+type FluxKontextModel = 'flux-kontext-pro' | 'flux-kontext-max';
+type AspectRatio = '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16';
+type OutputFormat = 'jpeg' | 'png';
+interface TextToImageParams {
+    model: FluxKontextModel;
+    prompt: string;
+    callback_url?: string;
+    aspect_ratio?: AspectRatio;
+    output_format?: OutputFormat;
+    input_image?: string;
+    /** Auto-translate prompt to English (default: true). */
+    enable_translation?: boolean;
+    prompt_upsampling?: boolean;
+    safety_tolerance?: number;
+    upload_cn?: boolean;
+    watermark?: string;
+}
+interface TaskCreateResponse {
+    id: string;
+}
+interface Image {
+    url: string;
+    origin_url?: string;
+}
+interface TextToImageResponse {
+    id: string;
+    status: AsyncTaskStatus;
+    images?: Image[];
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Resolved response returned by `textToImage.run()` after polling sees
+ * `status: 'completed'`. Narrows the base response so `images` is guaranteed
+ * non-optional in user code.
+ */
+type CompletedTextToImageResponse = TextToImageResponse & {
+    status: 'completed';
+    images: Image[];
+};
+
+declare class TextToImage {
+    private readonly http;
+    constructor(http: HttpClient);
+    run(params: TextToImageParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToImageResponse>;
+    create(params: TextToImageParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    get(id: string, options?: RequestOptions): Promise<TextToImageResponse>;
+}
+
+/**
+ * Flux Kontext text-to-image API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new FluxKontextClient({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://runapi.ai',
+ * });
+ *
+ * const result = await client.textToImage.run({
+ *   model: 'flux-kontext-pro',
+ *   prompt: 'A futuristic cityscape at night',
+ * });
+ * ```
+ */
+declare class FluxKontextClient {
+    /** Text-to-image operations. */
+    readonly textToImage: TextToImage;
+    constructor(options?: ClientOptions);
+}
+
+export { type AspectRatio, type CompletedTextToImageResponse, FluxKontextClient, type FluxKontextModel, type Image, type OutputFormat, type TaskCreateResponse, type TextToImageParams, type TextToImageResponse };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { AsyncTaskStatus, HttpClient, RequestOptions, PollingOptions, ClientOptions } from '@runapi.ai/core';
+export { AuthenticationError, InsufficientCreditsError, NetworkError, NotFoundError, RateLimitError, RunApiError, ServiceUnavailableError, TaskFailedError, TaskTimeoutError, TimeoutError, ValidationError } from '@runapi.ai/core';
+
+type FluxKontextModel = 'flux-kontext-pro' | 'flux-kontext-max';
+type AspectRatio = '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16';
+type OutputFormat = 'jpeg' | 'png';
+interface TextToImageParams {
+    model: FluxKontextModel;
+    prompt: string;
+    callback_url?: string;
+    aspect_ratio?: AspectRatio;
+    output_format?: OutputFormat;
+    input_image?: string;
+    /** Auto-translate prompt to English (default: true). */
+    enable_translation?: boolean;
+    prompt_upsampling?: boolean;
+    safety_tolerance?: number;
+    upload_cn?: boolean;
+    watermark?: string;
+}
+interface TaskCreateResponse {
+    id: string;
+}
+interface Image {
+    url: string;
+    origin_url?: string;
+}
+interface TextToImageResponse {
+    id: string;
+    status: AsyncTaskStatus;
+    images?: Image[];
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Resolved response returned by `textToImage.run()` after polling sees
+ * `status: 'completed'`. Narrows the base response so `images` is guaranteed
+ * non-optional in user code.
+ */
+type CompletedTextToImageResponse = TextToImageResponse & {
+    status: 'completed';
+    images: Image[];
+};
+
+declare class TextToImage {
+    private readonly http;
+    constructor(http: HttpClient);
+    run(params: TextToImageParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToImageResponse>;
+    create(params: TextToImageParams, options?: RequestOptions): Promise<TaskCreateResponse>;
+    get(id: string, options?: RequestOptions): Promise<TextToImageResponse>;
+}
+
+/**
+ * Flux Kontext text-to-image API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new FluxKontextClient({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://runapi.ai',
+ * });
+ *
+ * const result = await client.textToImage.run({
+ *   model: 'flux-kontext-pro',
+ *   prompt: 'A futuristic cityscape at night',
+ * });
+ * ```
+ */
+declare class FluxKontextClient {
+    /** Text-to-image operations. */
+    readonly textToImage: TextToImage;
+    constructor(options?: ClientOptions);
+}
+
+export { type AspectRatio, type CompletedTextToImageResponse, FluxKontextClient, type FluxKontextModel, type Image, type OutputFormat, type TaskCreateResponse, type TextToImageParams, type TextToImageResponse };

package/dist/index.js

@@ -0,0 +1,98 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => import_core3.AuthenticationError,
+  FluxKontextClient: () => FluxKontextClient,
+  InsufficientCreditsError: () => import_core3.InsufficientCreditsError,
+  NetworkError: () => import_core3.NetworkError,
+  NotFoundError: () => import_core3.NotFoundError,
+  RateLimitError: () => import_core3.RateLimitError,
+  RunApiError: () => import_core3.RunApiError,
+  ServiceUnavailableError: () => import_core3.ServiceUnavailableError,
+  TaskFailedError: () => import_core3.TaskFailedError,
+  TaskTimeoutError: () => import_core3.TaskTimeoutError,
+  TimeoutError: () => import_core3.TimeoutError,
+  ValidationError: () => import_core3.ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_core2 = require("@runapi.ai/core");
+
+// src/resources/text-to-image.ts
+var import_core = require("@runapi.ai/core");
+var import_internal = require("@runapi.ai/core/internal");
+var ENDPOINT = "/api/v1/flux_kontext/text_to_image";
+var TextToImage = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async run(params, options) {
+    const { id } = await this.create(params, options);
+    const response = await (0, import_internal.pollUntilComplete)(() => this.get(id, options), {
+      maxWaitMs: options?.maxWaitMs,
+      pollIntervalMs: options?.pollIntervalMs
+    });
+    return response;
+  }
+  async create(params, options) {
+    return this.http.request("POST", ENDPOINT, {
+      body: (0, import_core.compactParams)(params),
+      ...options
+    });
+  }
+  async get(id, options) {
+    return this.http.request("GET", `${ENDPOINT}/${id}`, {
+      ...options
+    });
+  }
+};
+
+// src/client.ts
+var FluxKontextClient = class {
+  /** Text-to-image operations. */
+  textToImage;
+  constructor(options = {}) {
+    const http = (0, import_core2.createHttpClient)(options);
+    this.textToImage = new TextToImage(http);
+  }
+};
+
+// src/index.ts
+var import_core3 = require("@runapi.ai/core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  FluxKontextClient,
+  InsufficientCreditsError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  RunApiError,
+  ServiceUnavailableError,
+  TaskFailedError,
+  TaskTimeoutError,
+  TimeoutError,
+  ValidationError
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/resources/text-to-image.ts"],"sourcesContent":["export { FluxKontextClient } from './client';\nexport * from './types';\n\n// Re-export core errors for convenience\nexport {\n  RunApiError,\n  AuthenticationError,\n  InsufficientCreditsError,\n  NotFoundError,\n  ValidationError,\n  RateLimitError,\n  ServiceUnavailableError,\n  NetworkError,\n  TimeoutError,\n  TaskTimeoutError,\n  TaskFailedError,\n} from '@runapi.ai/core';\n","import { createHttpClient, type ClientOptions } from '@runapi.ai/core';\nimport { TextToImage } from './resources/text-to-image';\n\n/**\n * Flux Kontext text-to-image API client.\n *\n * @example\n * ```typescript\n * const client = new FluxKontextClient({\n *   apiKey: 'your-api-key',\n *   baseUrl: 'https://runapi.ai',\n * });\n *\n * const result = await client.textToImage.run({\n *   model: 'flux-kontext-pro',\n *   prompt: 'A futuristic cityscape at night',\n * });\n * ```\n */\nexport class FluxKontextClient {\n  /** Text-to-image operations. */\n  public readonly textToImage: TextToImage;\n\n  constructor(options: ClientOptions = {}) {\n    const http = createHttpClient(options);\n    this.textToImage = new TextToImage(http);\n  }\n}\n","import type { HttpClient, RequestOptions, PollingOptions } from '@runapi.ai/core';\nimport { compactParams } from '@runapi.ai/core';\nimport { pollUntilComplete } from '@runapi.ai/core/internal';\nimport type {\n  CompletedTextToImageResponse,\n  TextToImageParams,\n  TextToImageResponse,\n  TaskCreateResponse,\n} from '../types';\n\nconst ENDPOINT = '/api/v1/flux_kontext/text_to_image';\n\nexport class TextToImage {\n  constructor(private readonly http: HttpClient) {}\n\n  async run(params: TextToImageParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToImageResponse> {\n    const { id } = await this.create(params, options);\n    const response = await pollUntilComplete<TextToImageResponse>(() => this.get(id, options), {\n      maxWaitMs: options?.maxWaitMs,\n      pollIntervalMs: options?.pollIntervalMs,\n    });\n    return response as CompletedTextToImageResponse;\n  }\n\n  async create(params: TextToImageParams, options?: RequestOptions): Promise<TaskCreateResponse> {\n    return this.http.request<TaskCreateResponse>('POST', ENDPOINT, {\n      body: compactParams(params),\n      ...options,\n    });\n  }\n\n  async get(id: string, options?: RequestOptions): Promise<TextToImageResponse> {\n    return this.http.request<TextToImageResponse>('GET', `${ENDPOINT}/${id}`, {\n      ...options,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,eAAqD;;;ACCrD,kBAA8B;AAC9B,sBAAkC;AAQlC,IAAM,WAAW;AAEV,IAAM,cAAN,MAAkB;AAAA,EACvB,YAA6B,MAAkB;AAAlB;AAAA,EAAmB;AAAA,EAAnB;AAAA,EAE7B,MAAM,IAAI,QAA2B,SAAkF;AACrH,UAAM,EAAE,GAAG,IAAI,MAAM,KAAK,OAAO,QAAQ,OAAO;AAChD,UAAM,WAAW,UAAM,mCAAuC,MAAM,KAAK,IAAI,IAAI,OAAO,GAAG;AAAA,MACzF,WAAW,SAAS;AAAA,MACpB,gBAAgB,SAAS;AAAA,IAC3B,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,OAAO,QAA2B,SAAuD;AAC7F,WAAO,KAAK,KAAK,QAA4B,QAAQ,UAAU;AAAA,MAC7D,UAAM,2BAAc,MAAM;AAAA,MAC1B,GAAG;AAAA,IACL,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,IAAI,IAAY,SAAwD;AAC5E,WAAO,KAAK,KAAK,QAA6B,OAAO,GAAG,QAAQ,IAAI,EAAE,IAAI;AAAA,MACxE,GAAG;AAAA,IACL,CAAC;AAAA,EACH;AACF;;;ADjBO,IAAM,oBAAN,MAAwB;AAAA;AAAA,EAEb;AAAA,EAEhB,YAAY,UAAyB,CAAC,GAAG;AACvC,UAAM,WAAO,+BAAiB,OAAO;AACrC,SAAK,cAAc,IAAI,YAAY,IAAI;AAAA,EACzC;AACF;;;ADvBA,IAAAC,eAYO;","names":["import_core","import_core"]}

package/dist/index.mjs

@@ -0,0 +1,72 @@
+// src/client.ts
+import { createHttpClient } from "@runapi.ai/core";
+
+// src/resources/text-to-image.ts
+import { compactParams } from "@runapi.ai/core";
+import { pollUntilComplete } from "@runapi.ai/core/internal";
+var ENDPOINT = "/api/v1/flux_kontext/text_to_image";
+var TextToImage = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async run(params, options) {
+    const { id } = await this.create(params, options);
+    const response = await pollUntilComplete(() => this.get(id, options), {
+      maxWaitMs: options?.maxWaitMs,
+      pollIntervalMs: options?.pollIntervalMs
+    });
+    return response;
+  }
+  async create(params, options) {
+    return this.http.request("POST", ENDPOINT, {
+      body: compactParams(params),
+      ...options
+    });
+  }
+  async get(id, options) {
+    return this.http.request("GET", `${ENDPOINT}/${id}`, {
+      ...options
+    });
+  }
+};
+
+// src/client.ts
+var FluxKontextClient = class {
+  /** Text-to-image operations. */
+  textToImage;
+  constructor(options = {}) {
+    const http = createHttpClient(options);
+    this.textToImage = new TextToImage(http);
+  }
+};
+
+// src/index.ts
+import {
+  RunApiError,
+  AuthenticationError,
+  InsufficientCreditsError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServiceUnavailableError,
+  NetworkError,
+  TimeoutError,
+  TaskTimeoutError,
+  TaskFailedError
+} from "@runapi.ai/core";
+export {
+  AuthenticationError,
+  FluxKontextClient,
+  InsufficientCreditsError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  RunApiError,
+  ServiceUnavailableError,
+  TaskFailedError,
+  TaskTimeoutError,
+  TimeoutError,
+  ValidationError
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/resources/text-to-image.ts","../src/index.ts"],"sourcesContent":["import { createHttpClient, type ClientOptions } from '@runapi.ai/core';\nimport { TextToImage } from './resources/text-to-image';\n\n/**\n * Flux Kontext text-to-image API client.\n *\n * @example\n * ```typescript\n * const client = new FluxKontextClient({\n *   apiKey: 'your-api-key',\n *   baseUrl: 'https://runapi.ai',\n * });\n *\n * const result = await client.textToImage.run({\n *   model: 'flux-kontext-pro',\n *   prompt: 'A futuristic cityscape at night',\n * });\n * ```\n */\nexport class FluxKontextClient {\n  /** Text-to-image operations. */\n  public readonly textToImage: TextToImage;\n\n  constructor(options: ClientOptions = {}) {\n    const http = createHttpClient(options);\n    this.textToImage = new TextToImage(http);\n  }\n}\n","import type { HttpClient, RequestOptions, PollingOptions } from '@runapi.ai/core';\nimport { compactParams } from '@runapi.ai/core';\nimport { pollUntilComplete } from '@runapi.ai/core/internal';\nimport type {\n  CompletedTextToImageResponse,\n  TextToImageParams,\n  TextToImageResponse,\n  TaskCreateResponse,\n} from '../types';\n\nconst ENDPOINT = '/api/v1/flux_kontext/text_to_image';\n\nexport class TextToImage {\n  constructor(private readonly http: HttpClient) {}\n\n  async run(params: TextToImageParams, options?: RequestOptions & PollingOptions): Promise<CompletedTextToImageResponse> {\n    const { id } = await this.create(params, options);\n    const response = await pollUntilComplete<TextToImageResponse>(() => this.get(id, options), {\n      maxWaitMs: options?.maxWaitMs,\n      pollIntervalMs: options?.pollIntervalMs,\n    });\n    return response as CompletedTextToImageResponse;\n  }\n\n  async create(params: TextToImageParams, options?: RequestOptions): Promise<TaskCreateResponse> {\n    return this.http.request<TaskCreateResponse>('POST', ENDPOINT, {\n      body: compactParams(params),\n      ...options,\n    });\n  }\n\n  async get(id: string, options?: RequestOptions): Promise<TextToImageResponse> {\n    return this.http.request<TextToImageResponse>('GET', `${ENDPOINT}/${id}`, {\n      ...options,\n    });\n  }\n}\n","export { FluxKontextClient } from './client';\nexport * from './types';\n\n// Re-export core errors for convenience\nexport {\n  RunApiError,\n  AuthenticationError,\n  InsufficientCreditsError,\n  NotFoundError,\n  ValidationError,\n  RateLimitError,\n  ServiceUnavailableError,\n  NetworkError,\n  TimeoutError,\n  TaskTimeoutError,\n  TaskFailedError,\n} from '@runapi.ai/core';\n"],"mappings":";AAAA,SAAS,wBAA4C;;;ACCrD,SAAS,qBAAqB;AAC9B,SAAS,yBAAyB;AAQlC,IAAM,WAAW;AAEV,IAAM,cAAN,MAAkB;AAAA,EACvB,YAA6B,MAAkB;AAAlB;AAAA,EAAmB;AAAA,EAAnB;AAAA,EAE7B,MAAM,IAAI,QAA2B,SAAkF;AACrH,UAAM,EAAE,GAAG,IAAI,MAAM,KAAK,OAAO,QAAQ,OAAO;AAChD,UAAM,WAAW,MAAM,kBAAuC,MAAM,KAAK,IAAI,IAAI,OAAO,GAAG;AAAA,MACzF,WAAW,SAAS;AAAA,MACpB,gBAAgB,SAAS;AAAA,IAC3B,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,OAAO,QAA2B,SAAuD;AAC7F,WAAO,KAAK,KAAK,QAA4B,QAAQ,UAAU;AAAA,MAC7D,MAAM,cAAc,MAAM;AAAA,MAC1B,GAAG;AAAA,IACL,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,IAAI,IAAY,SAAwD;AAC5E,WAAO,KAAK,KAAK,QAA6B,OAAO,GAAG,QAAQ,IAAI,EAAE,IAAI;AAAA,MACxE,GAAG;AAAA,IACL,CAAC;AAAA,EACH;AACF;;;ADjBO,IAAM,oBAAN,MAAwB;AAAA;AAAA,EAEb;AAAA,EAEhB,YAAY,UAAyB,CAAC,GAAG;AACvC,UAAM,OAAO,iBAAiB,OAAO;AACrC,SAAK,cAAc,IAAI,YAAY,IAAI;AAAA,EACzC;AACF;;;AEvBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@runapi.ai/flux-kontext",
+  "version": "0.2.0",
+  "description": "RunAPI Flux Kontext SDK for JavaScript, Ruby, and Go",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@runapi.ai/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "runapi",
+    "runapi-ai",
+    "flux-kontext",
+    "api",
+    "sdk",
+    "typescript",
+    "ruby",
+    "golang"
+  ],
+  "author": "RunAPI",
+  "license": "Apache-2.0",
+  "homepage": "https://runapi.ai/models/flux-kontext",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runapi-ai/flux-kontext-sdk.git"
+  }
+}

package/skills/flux-kontext/README.md

@@ -0,0 +1,52 @@
+# Flux Kontext API Skill for RunAPI
+
+Generate and transform images with Flux Kontext Pro and Max. This skill helps Claude Code, Codex, Gemini CLI, Cursor, and 50+ agents integrate Flux Kontext through RunAPI.
+
+The canonical agent file is `skills/flux-kontext/SKILL.md`.
+
+## Install
+
+```bash
+npx skills add runapi-ai/flux-kontext -g
+```
+
+Or manually: clone this repo and copy `skills/flux-kontext/` into your agent's skills directory.
+
+## Quick example
+
+```typescript
+import { FluxKontextClient } from '@runapi.ai/flux-kontext';
+
+const client = new FluxKontextClient();
+const result = await client.textToImage.run({
+  model: 'flux-kontext-pro',
+  prompt: 'A futuristic cityscape at night',
+  aspect_ratio: '16:9',
+});
+const url = result.images[0].url;
+```
+
+## Routing
+
+- Model page: https://runapi.ai/models/flux-kontext
+- Product docs: https://runapi.ai/docs#flux-kontext
+- SDK docs: https://runapi.ai/docs#sdk-flux-kontext
+- SDK repository: https://github.com/runapi-ai/flux-kontext-sdk
+- Pricing and rate limits: https://runapi.ai/models/flux-kontext/pro
+- Provider comparison: https://runapi.ai/providers/black-forest-labs
+- Browse all RunAPI models and skills: https://runapi.ai/models
+
+## Variants
+
+- [Flux Kontext Pro](https://runapi.ai/models/flux-kontext/pro)
+- [Flux Kontext Max](https://runapi.ai/models/flux-kontext/max)
+
+## Agent rules
+
+- Keep API keys in `RUNAPI_API_KEY` or RunAPI CLI config; never commit secrets.
+- Prefer `create`, `get`, and `run` JSON passthrough patterns instead of inventing flags for every model parameter.
+- For flux kontext api pricing, rate-limit, and commercial-usage answers, link to the variant page rather than the repository README.
+
+## License
+
+Licensed under the Apache License, Version 2.0.

package/skills/flux-kontext/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: flux-kontext
+description: Generate images (Flux Kontext Pro / Max text-to-image and image-to-image) through RunAPI.ai using the @runapi.ai/flux-kontext Node/TypeScript SDK. Use when the user asks to add Flux Kontext image generation or writes against @runapi.ai/flux-kontext. Triggers on "flux kontext", "flux-kontext", "image generation", "生成图片", "@runapi.ai/flux-kontext".
+documentation: https://runapi.ai/models/flux-kontext
+provider_page: https://runapi.ai/providers/black-forest-labs
+catalog: https://runapi.ai/models
+---
+# @runapi.ai/flux-kontext — RunAPI.ai Flux Kontext image generation
+
+Build Node / TypeScript integrations that generate and transform images through RunAPI.ai.
+
+## Setup
+
+Requires **Node 18+** (global `fetch`).
+
+```bash
+npm install @runapi.ai/flux-kontext
+```
+
+Set your API key in the environment:
+
+```dotenv
+# .env
+RUNAPI_API_KEY=runapi_xxx   # get one at https://runapi.ai/settings/api_keys
+```
+
+```ts
+import { FluxKontextClient } from '@runapi.ai/flux-kontext';
+
+// The SDK reads RUNAPI_API_KEY from the environment automatically.
+const client = new FluxKontextClient();
+```
+
+Pass `{ apiKey }` explicitly if you manage secrets differently. `baseUrl` defaults to `https://runapi.ai`; override only for local development.
+
+## Core recipe — text to image
+
+```ts
+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()` creates the task, auto-polls, and resolves only when the task completes — `images[0].url` is populated on success. On failure it throws `TaskFailedError`; on polling timeout it throws `TaskTimeoutError`. Use `run()` for scripts and short-lived processes. For request handlers, split it:
+
+```ts
+const { id } = await client.textToImage.create({ model: 'flux-kontext-pro', prompt: '...' });
+// return 202 immediately; fetch later:
+const status = await client.textToImage.get(id);
+if (status.status === 'completed') { /* ... */ }
+```
+
+Do not hold a web worker open waiting on `run()`. Split + webhook is the production pattern.
+
+`run()` polls every 2 s for up to 15 min by default. Tune when needed:
+
+```ts
+await client.textToImage.run(params, { maxWaitMs: 5 * 60_000, pollIntervalMs: 2_000 });
+```
+
+If `TaskTimeoutError` fires, the task is still running server-side — resume with `textToImage.get(id)` or finish via webhook.
+
+## Image-to-image — edit a source image
+
+Pass `input_image` (a single URL) along with your prompt:
+
+```ts
+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',
+});
+```
+
+## Models
+
+| `model` | Use case |
+|---|---|
+| `flux-kontext-pro` | Cost-efficient production output. |
+| `flux-kontext-max` | Higher-fidelity variant. |
+
+`aspect_ratio` values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. `output_format`: `jpeg` / `png`.
+
+Exact credit costs per model are shown at https://runapi.ai/pricing and in the dashboard — do not hardcode prices in application code.
+
+## Callbacks (webhooks)
+
+Pass `callback_url` on `create()` (or any `run()` call) and RunAPI will POST the final payload to you:
+
+```ts
+await client.textToImage.create({
+  model: 'flux-kontext-pro',
+  prompt: '...',
+  callback_url: 'https://your.app/webhooks/runapi/flux-kontext',
+});
+```
+
+Payload shape:
+
+```ts
+{ id: string; status: 'completed' | 'failed'; images?: { url: string; origin_url?: string }[]; error?: string }
+```
+
+**Always verify the signature before trusting the body.** RunAPI signs every callback with your account's Callback Secret (rotate at `/accounts/callback_secret`). Headers:
+
+- `X-Callback-Id` — UUID, store to make handler idempotent
+- `X-Callback-Timestamp` — unix seconds, reject if `|now - ts| > 300`
+- `X-Callback-Signature` — base64 HMAC-SHA256 over `` `${id}.${ts}.${rawBody}` `` using the base64-decoded secret
+
+```ts
+import crypto from 'node:crypto';
+
+function 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');
+  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
+}
+```
+
+Reply `2xx` within 10s; any non-2xx triggers retries.
+
+## Errors
+
+All errors are re-exported from `@runapi.ai/core`. Always `instanceof` — never string-match messages.
+
+| Error | Status | Action |
+|---|---|---|
+| `AuthenticationError` | 401 | abort; surface "reconnect your API key" |
+| `InsufficientCreditsError` | 402 | prompt user to top up at runapi.ai/billing |
+| `ValidationError` | 400 / 422 | fix params; do not retry |
+| `RateLimitError` | 429 | sleep `err.retryAfterMs`, then retry |
+| `ServiceUnavailableError` | 503 / 455 | retry with backoff; transient service issue |
+| `TaskFailedError` | — | show `err.details` to user; do not auto-retry |
+| `TaskTimeoutError` | — | re-poll with `textToImage.get(id)` |
+
+```ts
+import { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/flux-kontext';
+
+try {
+  await client.textToImage.run({ model: 'flux-kontext-pro', prompt: '...' });
+} catch (err) {
+  if (err instanceof InsufficientCreditsError) { /* surface top-up CTA */ }
+  else if (err instanceof TaskFailedError)       { /* show err.details */ }
+  else throw err;
+}
+```
+
+## Gotchas
+
+- `model` is required on every call.
+- `input_image` is a single URL (string), not an array — this is the one endpoint in the family that takes a scalar URL.
+- `enable_translation` defaults to `true` — the prompt is auto-translated to English. Set `false` to keep the raw prompt.
+- `callback_url` must be reachable from the public internet. `localhost` / `127.0.0.1` URLs will never fire — use a tunnel (cloudflared, ngrok, tailscale funnel) when developing locally.
+
+## Dig deeper
+
+Package README (full API surface, all params): `node_modules/@runapi.ai/flux-kontext/README.md`. Types: `@runapi.ai/flux-kontext/dist/types.d.ts`. Product docs: https://runapi.ai/docs.
+
+## RunAPI public routing
+
+flux kontext api public links use the API-379 catalog route map. The main flux kontext api page is https://runapi.ai/models/flux-kontext. SDK docs live at https://runapi.ai/docs#sdk-flux-kontext and product docs live at https://runapi.ai/docs#flux-kontext.
+
+Pricing, rate limits, and commercial usage for flux kontext api should point to the most specific variant page:
+- [Flux Kontext Pro](https://runapi.ai/models/flux-kontext/pro)
+- [Flux Kontext Max](https://runapi.ai/models/flux-kontext/max)
+
+Compare Flux Kontext with other Black Forest Labs models at https://runapi.ai/providers/black-forest-labs. Browse every RunAPI model and skill at https://runapi.ai/models. SDK repository: https://github.com/runapi-ai/flux-kontext-sdk. Skill repository: https://github.com/runapi-ai/flux-kontext.