@ohmygame/fal 0.0.0-stage → 0.1.0

package/.ohmygame-plugin/plugin.json

@@ -0,0 +1,207 @@
+{
+  "$schema": "https://www.ohmygame.ai/schema/plugin-2.json",
+  "id": "ohmygame/fal",
+  "version": "0.1.0",
+  "engines": {
+    "ohmygame-api": "^2.5.0"
+  },
+  "displayName": "%plugin.name%",
+  "description": "%plugin.description%",
+  "longDescription": "%plugin.longDescription%",
+  "icon": "./assets/icon.svg",
+  "categories": [
+    "provider"
+  ],
+  "capabilities": {
+    "network": [
+      "queue.fal.run",
+      "fal.media",
+      "v3.fal.media",
+      "v3b.fal.media"
+    ]
+  },
+  "configuration": {
+    "apiKey": {
+      "type": "secret",
+      "title": "%config.apiKey.title%",
+      "description": "%config.apiKey.description%"
+    }
+  },
+  "contributes": {
+    "providers": [
+      {
+        "id": "fal",
+        "title": "%plugin.name%",
+        "icon": "./assets/icon.svg",
+        "apiKey": "apiKey",
+        "media": {
+          "adapter": "./media/adapter.js",
+          "auth": {
+            "header": "authorization",
+            "scheme": "Key"
+          },
+          "image": {
+            "models": [
+              {
+                "id": "fal-ai/flux/schnell",
+                "title": "FLUX.1 [schnell]",
+                "resolutions": [
+                  "1K"
+                ],
+                "aspectRatios": [
+                  "1:1",
+                  "4:3",
+                  "3:4",
+                  "16:9",
+                  "9:16"
+                ],
+                "maxReferenceImages": 0
+              }
+            ]
+          },
+          "video": {
+            "maxMinutes": 30,
+            "models": [
+              {
+                "id": "fal-ai/kling-video/o3/standard/image-to-video",
+                "title": "Kling O3",
+                "durations": [
+                  3,
+                  5,
+                  10,
+                  15
+                ],
+                "resolutions": [
+                  "720p"
+                ],
+                "aspectRatios": [
+                  "adaptive"
+                ],
+                "maxReferenceImages": 2,
+                "referenceModes": [
+                  "frame"
+                ]
+              }
+            ]
+          },
+          "audio": {
+            "models": [
+              {
+                "id": "fal-ai/minimax/speech-02-hd",
+                "title": "MiniMax Speech-02 HD",
+                "kinds": [
+                  "speech"
+                ],
+                "readsText": true,
+                "voices": [
+                  {
+                    "id": "Wise_Woman",
+                    "name": "Wise Woman"
+                  },
+                  {
+                    "id": "Friendly_Person",
+                    "name": "Friendly Person"
+                  },
+                  {
+                    "id": "Inspirational_girl",
+                    "name": "Inspirational girl"
+                  },
+                  {
+                    "id": "Deep_Voice_Man",
+                    "name": "Deep Voice Man"
+                  },
+                  {
+                    "id": "Calm_Woman",
+                    "name": "Calm Woman"
+                  },
+                  {
+                    "id": "Casual_Guy",
+                    "name": "Casual Guy"
+                  },
+                  {
+                    "id": "Lively_Girl",
+                    "name": "Lively Girl"
+                  },
+                  {
+                    "id": "Patient_Man",
+                    "name": "Patient Man"
+                  },
+                  {
+                    "id": "Young_Knight",
+                    "name": "Young Knight"
+                  },
+                  {
+                    "id": "Determined_Man",
+                    "name": "Determined Man"
+                  },
+                  {
+                    "id": "Lovely_Girl",
+                    "name": "Lovely Girl"
+                  },
+                  {
+                    "id": "Decent_Boy",
+                    "name": "Decent Boy"
+                  },
+                  {
+                    "id": "Imposing_Manner",
+                    "name": "Imposing Manner"
+                  },
+                  {
+                    "id": "Elegant_Man",
+                    "name": "Elegant Man"
+                  },
+                  {
+                    "id": "Abbess",
+                    "name": "Abbess"
+                  },
+                  {
+                    "id": "Sweet_Girl_2",
+                    "name": "Sweet Girl 2"
+                  },
+                  {
+                    "id": "Exuberant_Girl",
+                    "name": "Exuberant Girl"
+                  }
+                ],
+                "formats": [
+                  "mp3"
+                ],
+                "maxTextCharacters": 5000
+              },
+              {
+                "id": "fal-ai/stable-audio",
+                "title": "Stable Audio",
+                "kinds": [
+                  "sound-effect",
+                  "music"
+                ],
+                "formats": [
+                  "wav"
+                ],
+                "minDurationSeconds": 1,
+                "maxDurationSeconds": 47
+              }
+            ]
+          },
+          "3d": {
+            "models": [
+              {
+                "id": "fal-ai/trellis",
+                "title": "TRELLIS",
+                "operations": [
+                  "image"
+                ],
+                "maxReferenceImages": 1,
+                "polycount": {
+                  "min": 20000,
+                  "max": 20000,
+                  "default": 20000
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  }
+}

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# fal.ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adds fal.ai to OhMyGame's Settings → Providers, with your own API key, for
+pictures, videos, audio and 3D models. It has no chat models.
+
+- API key: From fal.ai → Dashboard → Keys.
+
+| Kind | Model | What it takes |
+| --- | --- | --- |
+| Image | FLUX.1 [schnell] (`fal-ai/flux/schnell`) | A prompt, in 1:1, 4:3, 3:4, 16:9 or 9:16 |
+| Video | Kling O3 (`fal-ai/kling-video/o3/standard/image-to-video`) | A first frame, an optional last frame, and 3, 5, 10 or 15 seconds |
+| Speech | MiniMax Speech-02 HD (`fal-ai/minimax/speech-02-hd`) | Up to 5,000 characters, in one of MiniMax's voices, as MP3 |
+| Sound effects, music | Stable Audio (`fal-ai/stable-audio`) | A description and up to 47 seconds, as WAV |
+| 3D | TRELLIS (`fal-ai/trellis`) | One picture of the object, as GLB |
+
+Every request goes through fal.ai's queue, in
+[`media/adapter.js`](media/adapter.js). OhMyGame runs that script in a sandbox:
+it reaches only `queue.fal.run` and the hosts fal.ai's files are on, and
+OhMyGame adds the key to its requests. A video, audio file or 3D model a
+restart cut off is checked again on **Retry**, not paid for twice. fal.ai bills
+each request to your account.
+
+Needs OhMyGame with plugin API 2.5.0 or later.
+
+Published as `@ohmygame/fal` from [ohmygame-plugins](https://github.com/WhiteTowerAI/ohmygame-plugins).

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><rect width="24" height="24" rx="6" fill="#111827"/><path d="M12 4.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15zm0 3.75a3.75 3.75 0 1 1 0 7.5 3.75 3.75 0 0 1 0-7.5z" fill="#A78BFA" fill-rule="evenodd"/></svg>

package/locales/en.json

@@ -0,0 +1,7 @@
+{
+  "plugin.name": "fal.ai",
+  "plugin.description": "fal.ai's image, video, audio and 3D models, with your own API key.",
+  "plugin.longDescription": "Adds fal.ai to Settings → Providers. Enter your API key here or in Settings: FLUX.1 [schnell] makes pictures, Kling O3 makes videos of 3 to 15 seconds from a first frame (and a last one if you give it), MiniMax Speech-02 HD reads text aloud, Stable Audio makes sound effects and music, and TRELLIS makes a 3D model from a picture. fal.ai bills each request to your account.",
+  "config.apiKey.title": "fal.ai API key",
+  "config.apiKey.description": "From fal.ai → Dashboard → Keys."
+}

package/locales/zh-CN.json

@@ -0,0 +1,7 @@
+{
+  "plugin.name": "fal.ai",
+  "plugin.description": "用你自己的 API key，使用 fal.ai 的图片、视频、音频和 3D 模型。",
+  "plugin.longDescription": "把 fal.ai 加入 设置 → 服务商。在这里或设置里填好 API key：FLUX.1 [schnell] 生成图片，Kling O3 根据首帧（可加尾帧）生成 3 到 15 秒的视频，MiniMax Speech-02 HD 朗读文本，Stable Audio 生成音效和音乐，TRELLIS 根据图片生成 3D 模型。每次请求由 fal.ai 向你的账户计费。",
+  "config.apiKey.title": "fal.ai API key",
+  "config.apiKey.description": "在 fal.ai → Dashboard → Keys 创建。"
+}

package/media/adapter.js

@@ -0,0 +1,136 @@
+// fal.ai's queue API for OhMyGame (docs.fal.ai: model endpoints, queue).
+// Runs in OhMyGame's sandbox: host.fetch reaches only the hosts in
+// capabilities.network, and `auth: true` adds the key ("Key <key>"), which
+// this script never sees.
+//
+// Every model goes through the same queue: `start` submits the request, `check`
+// reads its status and, once it's done, its result, and `cancel` withdraws it.
+// The queue answers with the addresses to use, so they're kept as the task.
+
+const QUEUE = "https://queue.fal.run/";
+
+// FLUX's named sizes for the aspect ratios it's offered with.
+const IMAGE_SIZES = {
+  "1:1": "square_hd", "4:3": "landscape_4_3", "3:4": "portrait_4_3", "16:9": "landscape_16_9", "9:16": "portrait_16_9",
+};
+
+/** The answer's JSON, and its message when fal.ai refused the request. */
+async function read(response) {
+  const text = await response.text();
+  let answer;
+  try { answer = JSON.parse(text); } catch { answer = undefined; }
+  const detail = answer && answer.detail;
+  const message = (typeof detail === "string" && detail)
+    // A validation error lists what was wrong with each field.
+    || (Array.isArray(detail) && detail.map((item) => item && item.msg).filter(Boolean).join("; "))
+    || text.slice(0, 300)
+    || `fal.ai answered ${response.status}`;
+  return { answer, message };
+}
+
+function dataUri(picture) {
+  return `data:${picture.mediaType};base64,${picture.base64}`;
+}
+
+function onQueue(url) {
+  return typeof url === "string" && url.startsWith(QUEUE);
+}
+
+/** Submits a request to a model's queue. */
+async function submit(model, body, host) {
+  const response = await host.fetch(QUEUE + model, { method: "POST", auth: true, json: body });
+  const { answer, message } = await read(response);
+  // A server error may come after fal.ai took the request: throwing has OhMyGame
+  // treat it as possibly sent, so a retry doesn't pay again. A refusal can be tried again.
+  if (response.status >= 500) throw new Error(message);
+  if (!response.ok) return { error: message };
+  const task = answer && { status: answer.status_url, result: answer.response_url, cancel: answer.cancel_url };
+  // Taken but unreadable: thrown for the same reason as a server error.
+  if (!task || !onQueue(task.status) || !onQueue(task.result)) throw new Error("fal.ai returned no request to follow");
+  return { task };
+}
+
+/** Reads a request's status, then its result with `pick` once it's done. */
+async function follow(task, host, retryAfter, pick) {
+  const response = await host.fetch(task.status, { method: "GET", auth: true });
+  const { answer, message } = await read(response);
+  // A busy service is checked again (OhMyGame retries a failed check); a refusal ends the task.
+  if (response.status === 429 || response.status >= 500) throw new Error(message);
+  if (!response.ok) return { error: message };
+  const status = answer && answer.status;
+  if (status === "IN_QUEUE" || status === "IN_PROGRESS") return { retryAfter };
+  if (status !== "COMPLETED") throw new Error(`fal.ai answered with status ${String(status)}`);
+  if (answer.error) return { error: String(answer.error) };
+  const result = await host.fetch(task.result, { method: "GET", auth: true });
+  const output = await read(result);
+  if (result.status === 429 || result.status >= 500) throw new Error(output.message);
+  if (!result.ok) return { error: output.message };
+  // fal.ai keeps the file for a while; OhMyGame downloads it at once.
+  const url = output.answer && pick(output.answer);
+  return typeof url === "string" && url ? { outputs: [{ url }] } : { error: "fal.ai returned no file" };
+}
+
+async function cancel(task, host) {
+  if (onQueue(task.cancel)) await host.fetch(task.cancel, { method: "PUT", auth: true });
+}
+
+export default {
+  image: {
+    start(input, host) {
+      return submit(input.model, {
+        prompt: input.prompt,
+        image_size: IMAGE_SIZES[input.aspectRatio] || "square_hd",
+        num_images: 1,
+        output_format: "png",
+      }, host);
+    },
+    check: (task, host) => follow(task, host, 1, (answer) => answer.images && answer.images[0] && answer.images[0].url),
+    cancel,
+  },
+
+  video: {
+    start(input, host) {
+      const [first, last] = input.references;
+      if (!first) return { error: "Kling O3 on fal.ai makes a video from a first frame: add a picture." };
+      const body = { image_url: dataUri(first), duration: String(input.duration) };
+      if (input.prompt) body.prompt = input.prompt;
+      if (last) body.end_image_url = dataUri(last);
+      return submit(input.model, body, host);
+    },
+    check: (task, host) => follow(task, host, 5, (answer) => answer.video && answer.video.url),
+    cancel,
+  },
+
+  audio: {
+    start(input, host) {
+      if (input.model === "fal-ai/minimax/speech-02-hd") {
+        // OhMyGame's speed runs from -50 (half as fast) to 100 (twice as fast); MiniMax's from 0.5 to 2.
+        const speed = Math.min(2, Math.max(0.5, 1 + (input.speed || 0) / 100));
+        return submit(input.model, {
+          text: input.prompt,
+          voice_setting: { voice_id: input.voiceId || "Wise_Woman", speed },
+          audio_setting: { format: "mp3" },
+          output_format: "url",
+        }, host);
+      }
+      if (input.model === "fal-ai/stable-audio") {
+        const body = { prompt: input.prompt };
+        if (input.durationSeconds) body.seconds_total = input.durationSeconds;
+        return submit(input.model, body, host);
+      }
+      return { error: `${input.model} isn't offered here` };
+    },
+    check: (task, host) => follow(task, host, 2, (answer) => (answer.audio && answer.audio.url) || (answer.audio_file && answer.audio_file.url)),
+    cancel,
+  },
+
+  "3d": {
+    start(input, host) {
+      const front = input.references && input.references[0];
+      if (input.operation !== "image" || !front) return { error: "TRELLIS on fal.ai makes a 3D model from a picture: add one." };
+      return submit(input.model, { image_url: dataUri(front) }, host);
+    },
+    check: (task, host) => follow(task, host, 5, (answer) => answer.model_mesh && answer.model_mesh.url),
+    cancel,
+  },
+};

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@ohmygame/fal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "fal.ai's image, video, audio and 3D models, with your own API key.",
+  "keywords": [
+    "ohmygame-plugin",
+    "model-provider",
+    "fal",
+    "media"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WhiteTowerAI/ohmygame-plugins.git",
+    "directory": "plugins/fal"
+  },
+  "homepage": "https://github.com/WhiteTowerAI/ohmygame-plugins/tree/main/plugins/fal#readme",
+  "files": [
+    ".ohmygame-plugin",
+    "assets",
+    "locales",
+    "media"
+  ],
+  "scripts": {
+    "check": "ohmygame-plugin check",
+    "pack": "ohmygame-plugin pack"
+  },
+  "devDependencies": {
+    "@ohmygame/plugin-cli": "^2.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}