Metadata-Version: 2.5
Name: lfx-acedatacloud
Version: 0.1.4
Summary: Ace Data Cloud model provider and service components for Langflow
Project-URL: Homepage, https://platform.acedata.cloud?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=langflowacedatacloud_package_homepage
Project-URL: Documentation, https://github.com/AceDataCloud/LangflowAceDataCloud
Project-URL: Repository, https://github.com/AceDataCloud/LangflowAceDataCloud
Author-email: Ace Data Cloud <dev@acedata.cloud>
License-Expression: MIT
License-File: LICENSE
Keywords: acedatacloud,gpt-image,happyhorse,langflow,lfx,nano-banana,seedance,suno
Requires-Python: <3.15,>=3.10
Requires-Dist: httpx<1,>=0.24
Requires-Dist: langchain-openai<2,>=1.1.6
Requires-Dist: lfx<2,>=1.12.5
Description-Content-Type: text/markdown

# Ace Data Cloud for Langflow

Use Ace Data Cloud chat models and service components in Langflow 1.12.5 or later. One Extension Bundle supplies a named **Ace Data Cloud** model provider and separate components for 17 image, video, audio, search, and face service families. The examples contain no credentials.

[简体中文教程](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/README_zh_CN.md) · [Current models and prices](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=langflowacedatacloud_readme_pricing) · [Source](https://github.com/AceDataCloud/LangflowAceDataCloud)

> **Version 0.1.4:** install the aggregate or a single service using the wheels in the [GitHub release](https://github.com/AceDataCloud/LangflowAceDataCloud/releases/tag/v0.1.4). [Official Langflow default inclusion](https://github.com/langflow-ai/langflow/pull/15659) remains under review.


## Find the service you already know

Search the component palette for **suno**, **seedance**, **happyhorse**, **gpt image**, or **nano banana**. The extension exposes independent **Generate** and **Retrieve Task** nodes with service-first labels ending **by Ace Data Cloud**, category-appropriate audio/video/image icons, and their own guide links. Existing `ext:ace_data_cloud:<Class>@official` saved-flow IDs are unchanged.

- [Suno music and audio](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/suno.md) · [中文](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/suno_zh_CN.md)
- [Seedance video](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/seedance.md) · [中文](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/seedance_zh_CN.md)
- [Happy Horse video](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/happy-horse.md) · [中文](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/happy-horse_zh_CN.md)
- [GPT Image images](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/gpt-image.md) · [中文](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/gpt-image_zh_CN.md)
- [Nano Banana images](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/nano-banana.md) · [中文](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/guides/nano-banana_zh_CN.md)

These integrations are provided by Ace Data Cloud and do not claim endorsement by the service owners. Historical screenshots below retain their original date, Langflow version and labels.

## 1. Install the extension

### Install only one service

> **PyPI availability:** Suno and Seedance project creation is temporarily rate-limited by PyPI. Both 0.1.4 wheels are already available in the GitHub release; install them directly using the URLs below. The aggregate, GPT Image, HappyHorse and Nano Banana have PyPI listings; use a version from PyPI only after it appears in that listing. No separate account is required to install a public wheel.

| Service | Distribution | Install in Langflow's Python environment |
| --- | --- | --- |
| Suno | `lfx-acedatacloud-suno` | `python -m pip install "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud_suno-0.1.4-py3-none-any.whl"` |
| Seedance | `lfx-acedatacloud-seedance` | `python -m pip install "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud_seedance-0.1.4-py3-none-any.whl"` |
| HappyHorse | `lfx-acedatacloud-happyhorse` | `python -m pip install "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud_happyhorse-0.1.4-py3-none-any.whl"` |
| GPT Image | `lfx-acedatacloud-gpt-image` | `python -m pip install "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud_gpt_image-0.1.4-py3-none-any.whl"` |
| Nano Banana | `lfx-acedatacloud-nano-banana` | `python -m pip install "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud_nano_banana-0.1.4-py3-none-any.whl"` |

Each service package registers only Generate and Retrieve Task under **Components → service name by Ace Data Cloud**, with no chat provider or aggregate dependency. Restart an existing server after installation. Each wheel includes matching no-key flows in its Python package's `examples/` directory.

Service flows use `ext:ace_<service>:*` IDs. Root `examples/` keep aggregate `ext:ace_data_cloud:*` IDs and require the aggregate. All five packages can coexist; with the aggregate installed, both categories remain so saved flows keep their IDs. Installation does not migrate saved nodes.

### Install the aggregate and native chat provider

```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install "langflow==1.12.6" "https://github.com/AceDataCloud/LangflowAceDataCloud/releases/download/v0.1.4/lfx_acedatacloud-0.1.4-py3-none-any.whl"
lfx extension list
langflow run
```

The [v0.1.4 GitHub release](https://github.com/AceDataCloud/LangflowAceDataCloud/releases/tag/v0.1.4) provides the same six distributions as wheels and source archives. The aggregate wheel is `lfx_acedatacloud-0.1.4-py3-none-any.whl`. Install downloaded wheels in the server's Python environment, then restart. The aggregate exposes 17 generation actions, 15 task readers and the named Ace Data Cloud model provider under **Components → Ace Data Cloud**.

![Historical Ace component group on Langflow 1.12.5](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/04-service-components.png)

## 2. Create an API key with the right access

New account? Register and sign in first. If the Applications page has no General application yet, choose **Initialize General Application**, then continue with the key steps below.

1. Sign in to [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=langflowacedatacloud_readme_api_key) and open **General application**. A general-application key can use the services your account has access to; a service-specific key is limited to that service.
2. To reuse the selected key, click the copy icon marked **1** below. For a separate Langflow key, click **Manage Keys** marked **2**, then **Create**.

![Copy the selected key or open Manage Keys](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/get-api-key-en.png)

3. Name the new key, for example `Langflow tutorial`, and set expiration, usage and **Allowed APIs** restrictions as needed. Click **Create**, return to the list or application card, and copy the token.

![Create an optional separate API key](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/create-api-key-en.png)

4. Check service access, current price and balance before a paid run. If **Allowed APIs** is enabled, include both routes used by the flow: `/openai/images/generations` and `/openai/tasks` for GPT Image; `/v1/models` and `/v1/chat/completions` for the chat model. Copy only the token string. Do not prepend `Bearer `, use a platform management token, or put the key in a prompt, flow export or screenshot.

## 3. Store the key in Langflow

Choose your profile icon → **Settings → Global Variables → Add New**. Set **Type** to **Credential**, **Name** to `ACEDATACLOUD_API_KEY`, paste the token into **Value**, then choose **Save Variable**. The saved value is masked.

![Langflow's Create Variable dialog before a key is entered](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/17-create-credential.png)

![Credential global variable saved with its value masked](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/18-saved-credential.png)

The same variable connects the named model provider. Open **Settings → Model Providers → Ace Data Cloud** and check the API Key shows as connected. Version 0.1.2 used the earlier 84-ID filter. Version 0.1.3 refreshes the list from the current public chat catalog and the models visible to your key, so new text models do not need a package update with this release. Enable the specific model you want to use.

![Named Ace Data Cloud provider in Langflow settings](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/26-model-provider-settings.png)

![Connected provider credential and model list, with the key masked](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/27-model-provider-detail.png)

On each service node, click the globe icon in **Ace Data Cloud API key** and select `ACEDATACLOUD_API_KEY`. The first GPT Image flow has **two** key fields: one on Generate and one on Retrieve Task. Bind both. A global variable reference saves the variable name in the flow; the token stays in Langflow's credential store. Before sharing an exported flow, inspect it for literal secrets. In our Langflow 1.12.5 test, enabling `LANGFLOW_REMOVE_API_KEYS=true` also removed this field's global-variable reference on reload; use the default setting for persistent binding and confirm the reference survives a reload.

## 4. Try the chat model provider

On the Projects page, click **Upload a flow** and select [`examples/chat_model.json`](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/chat_model.json). It has a Language Model node set to **Ace Data Cloud → `gpt-4.1-mini`**, connected to Chat Output. Its fixed input says `Reply with exactly OK.`. The API Key override is empty so Langflow uses the provider credential configured above. Click the **Run component** triangle on Chat Output once, then inspect the output or **Traces**.

![Ready-to-import chat model flow](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/31-chat-model-flow.png)

The recorded test returned `OK` using 11 input and 5 output tokens. The model and reply were verified in the flow trace and one matching Credits usage record. Your response and charge depend on the current model and account.

![Actual Ace Data Cloud model response in Langflow Traces](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/33-chat-model-trace.png)

## 5. Generate one GPT Image and query the same task

Upload [`examples/gpt_image.json`](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/gpt_image.json). Langflow 1.12.5 accepted the no-key JSON and displayed this path:

![The no-key flow uploaded successfully in Projects](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/12-import-result.png)

**GPT Image Generate → GPT Image Retrieve Task → Chat Output**

![Actual imported GPT Image flow with two connections](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/13-imported-gpt-image-flow.png)

Bind `ACEDATACLOUD_API_KEY` to both Ace nodes. The example already sets these first-run values; leave other parameters empty:

| Field | Value |
| --- | --- |
| Prompt | `A single blue paper sphere on a plain cream background, clean studio photograph, no text.` |
| Model | `gpt-image-2` |
| Size | `1024x1024` |
| Quality | `low` |
| Image count | `1` |
| Additional route parameters | `{"async": true}` |
| Retrieve Task → Wait up to seconds | `240` |

In the editor, select Generate → **Parameters → Add** on **Additional route parameters** to inspect the prefilled `async=true` pair. It requests a task ID without waiting for the full media generation in the submit call.

![The real 0.1.1 Langflow form with async true visible](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/41-async-first-run.png)

Click **Run component** on **Chat Output once**. Generate makes one paid submission and requests an immediate task ID. Its returned `task_id` is connected to Retrieve Task's **Submitted task** input. Retrieve Task uses only `/openai/tasks` and waits up to 240 seconds for that same ID. A green flow before the service task is terminal is not proof that the media is ready.

![One completed Langflow run with both API components and a masked credential reference](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/21-gpt-image-run.png)

![One successful run in Flow Activity](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/22-run-traces.png)

The real test returned `status=succeeded`, `success=true`, task ID `ac4ffabb-ada6-4689-b275-7e9f9928493a`, and one PNG URL. The returned media was opened over HTTPS and its response was `200 image/png`.

![Actual task output in Langflow Traces](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/25-task-output.png)

![Image produced by that run](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/38-generated-image.png)

If the result is still `pending`, **do not rerun the generation flow**. That would submit another paid task. Import [`examples/retrieve_only/gpt_image.json`](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/gpt_image.json), bind the same Credential variable, paste the original task ID into **Task ID**, and run Chat Output. This flow contains no generation node. Repeat this read-only flow until the task is terminal.

If a submission times out after the service accepted it, check Usage History before another submission. GPT Image, Midjourney, and Veo task readers also accept a **Trace ID** from request history when the task ID was not returned. For other services, recover the task ID from the original usage record or ask support with its trace ID. Query the recovered task; never regenerate only to learn its status.

![An actual Midjourney result recovered in a query-only Langflow flow using its trace ID](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/39-trace-recovery.png)

![Separate task lookup with the original task ID](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/34-retrieve-only.png)

![The retrieve-only flow completed without a generation node](https://raw.githubusercontent.com/AceDataCloud/LangflowAceDataCloud/v0.1.4/_assets/tutorial/35-retrieve-only-run.png)

## 6. Check the charge

In [Ace Data Cloud → Usage History](https://platform.acedata.cloud/console/usages?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=langflowacedatacloud_readme_usage), filter to the relevant API, key, and time, then compare the task or trace ID. The completed GPT Image test had trace ID `813ac552-4724-4d05-8b17-3c93534fbed6`; the platform returned **one** HTTP 200 usage record for that trace and deducted **0.099 Credits**. Langflow's task output also reported `cost.amount=0.099` in `credit` currency. This is evidence for that single test, not a fixed future price. Read your account's current package rate if you need a USD conversion.

The chat model example had one matching usage record for `gpt-4.1-mini`, 16 tokens, and `0.0000234636021` Credits. [Sanitized run evidence](https://github.com/AceDataCloud/LangflowAceDataCloud/tree/v0.1.4/tests/evidence/) keeps task, media, import, and billing readbacks separate.

## Other service examples

Each file below is a no-key first-run flow. For asynchronous services, the matching `retrieve_only` file queries an existing task ID without another submission. Each named component exposes the listed first-run action and an allowlisted **Additional route parameters** field. These are focused entry points; they do not claim every advanced action supported by the underlying API.

The 15 asynchronous first-run flows and newly added media components prefill `{"async": true}` so the task reader can query promptly. Fish Audio can also finish synchronously when used without that option; a connected completed result passes through its reader without another API call.

The exact public routes, default values, and proof level for each action are in [Capabilities](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/CAPABILITIES.md).

| Service | First-run action | Import flow | Task lookup |
| --- | --- | --- | --- |
| GPT Image | Generate one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/gpt_image.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/gpt_image.json) |
| Suno | Generate instrumental audio | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/suno.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/suno.json) |
| Seedance | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/seedance.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/seedance.json) |
| Fish Audio | Text-to-speech | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/fish_audio.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/fish_audio.json) |
| Seedream | Generate one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/seedream.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/seedream.json) |
| Happy Horse | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/happy_horse.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/happy_horse.json) |
| Qwen Image | Generate one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/qwen_image.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/qwen_image.json) |
| Veo | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/veo.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/veo.json) |
| Google Search | Web search, synchronous | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/google_search.json) | No task ID |
| Grok Video | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/grok.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/grok.json) |
| Face Transform | Analyze face keypoints, synchronous | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/face_transform.json) | No task ID |
| Midjourney | Imagine one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/midjourney.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/midjourney.json) |
| Flux | Generate one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/flux.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/flux.json) |
| MiniMax H3 | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/minimax_h3.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/minimax_h3.json) |
| Wan | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/wan.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/wan.json) |
| Kling | Generate text-to-video | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/kling.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/kling.json) |
| Nano Banana | Generate one image | [Flow](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/nano_banana.json) | [Lookup](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/examples/retrieve_only/nano_banana.json) |

All 18 first-run JSON flows (one model plus 17 services) and all 15 retrieve-only flows were imported into Langflow 1.12.5. The 15 readers first retrieved existing completed tasks without submitting generation. We then made exactly one new paid submission through each of the other 14 media Component classes: all 14 tasks completed, their first media URLs returned HTTP 200, and each matched one Credits usage record. Those 14 calls deducted 19.302232 Credits in total; see [sanitized per-service evidence](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/tests/evidence/media-generation-live.json). Midjourney and Grok's original synchronous submit calls timed out after the service accepted them; both tasks were recovered from usage records and completed without a paid retry. The imported UI flow itself was run end to end for GPT Image and the chat model; the other service flows were imported and their component methods were called, but their full UI graph execution has not been claimed.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| Bundle missing | Install in Langflow's Python environment, run `lfx extension list`, then restart the server. |
| Provider missing or zero models | Check **Settings → Model Providers**, the Credential global variable, `/v1/models` access, and the desired model toggle. |
| 401 or 403 | Check the full application API key, allowed API routes, service entitlement, expiry, and balance. Do not paste `Bearer ` into the key field. |
| 400 | Check the exact model, action, duration, size, and any additional parameters. This bundle fixes the public route for each first-run action. |
| `pending` or no media | Query the same task ID with the retrieve-only flow. Do not click Generate again to poll. |
| 429 | Wait and reduce concurrency. Do not enable automatic paid retries. |
| Timeout or 5xx | Check request history and task status before deciding whether a new submission is needed. Use the task reader's Trace ID field where available. Give support the task or trace ID, never the key. |

## Privacy, scope, and development

The extension sends the selected inputs and Bearer token to `https://api.acedata.cloud`. Secrets belong in Langflow Credential global variables. Generated media links can be shared by anyone who has the URL; handle exported flows and outputs accordingly. The extension itself is free; Ace Data Cloud API usage follows the current service price and your account balance. See [Privacy](https://github.com/AceDataCloud/LangflowAceDataCloud/blob/v0.1.4/PRIVACY.md), [Issues](https://github.com/AceDataCloud/LangflowAceDataCloud/issues), or dev@acedata.cloud.

To develop or review the package:

```bash
uv pip install -e .
lfx extension validate src/lfx_acedatacloud --execute-imports
pytest -q tests
python -m build
```

The public `BUNDLE_API_VERSION=1` manifest and separate provider/component IDs are checked against Langflow 1.12.5. Package installation, official Langflow source acceptance, default inclusion, and live service completion are tracked as distinct outcomes.
