DEV Community: Germey

A Practical Guide to Music Generation in Claude Code with MCP

Germey — Sat, 22 Aug 2026 01:07:52 +0000

How to Build an Async Text-to-Video Workflow with a REST API

Germey — Thu, 20 Aug 2026 01:17:06 +0000

Video generation is easy to demo and surprisingly easy to make unreliable: a browser request waits too long, the user refreshes, and the app loses track of the generated file.

This guide shows a practical way to integrate the Hailuo Videos Generation API as an asynchronous workflow. The goal is not just to send a prompt, but to keep enough state to connect a request, a callback, and the final video_url inside your own product.

What you can do

The documented endpoint is:

Base URL: https://api.acedata.cloud
Endpoint: POST /hailuo/videos
Headers: accept: application/json, authorization: Bearer {token}, and content-type: application/json
Action: generate
Models: minimax-t2v for text-to-video and minimax-i2v for image-to-video

The main request fields are action, model, prompt, first_image_url, callback_url, and async. The first_image_url field is required when using minimax-i2v, and the documentation notes that Base64 is not supported for that field.

Start with a text-to-video request

For a local test, begin with the same endpoint and a minimal JSON body.

curl -X POST 'https://api.acedata.cloud/hailuo/videos' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "minimax-t2v",
    "prompt": "A quiet city street after rain, reflections on the pavement, slow cinematic camera movement"
  }'

A successful response includes success, task_id, trace_id, and a data array. Each item can include id, model, prompt, video_url, and state.

{
  "success": true,
  "task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
  "trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
  "data": [
    {
      "id": "0pv8yhe4fdrge0cmckpv23pd2g",
      "model": "minimax-t2v",
      "prompt": "Internal heat",
      "video_url": "https://platform.cdn.acedata.cloud/.../output.mp4",
      "state": "succeeded"
    }
  ]
}

For an app, store at least task_id, trace_id, prompt, model, state, and video_url.

Add image-to-video without changing your pipeline

The image-to-video path uses the same endpoint and action, but switches the model to minimax-i2v and adds first_image_url.

{
  "action": "generate",
  "model": "minimax-i2v",
  "first_image_url": "https://example.com/first-frame.png",
  "prompt": "Animate the scene with a slow forward camera move and soft natural motion"
}

Because Base64 is not supported for first_image_url, your app should upload the first frame to object storage or another public URL before calling the API. Keeping both modes in the same video_jobs table is usually cleaner than building two systems.

Use callbacks for production-style requests

Video generation may take around 1–2 minutes. Holding a client HTTP request open for that long is fragile, so the API supports asynchronous callbacks through callback_url.

curl -X POST 'https://api.acedata.cloud/hailuo/videos' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "minimax-t2v",
    "prompt": "A product prototype floating above a dark desk, subtle light sweep, cinematic 6 second loop",
    "callback_url": "https://example.com/webhooks/hailuo"
  }'

With callback_url, the API immediately returns a JSON object containing task_id. Later, your webhook receives a POST JSON payload containing the same task_id, plus fields such as success, trace_id, data[].id, data[].model, data[].prompt, data[].video_url, and data[].state.

A simple webhook handler can look up the local job by task_id, store trace_id, state, and video_url, then mark the job as finished when state is succeeded.

Handle errors deliberately

The documented error response includes success: false, an error object, and trace_id.

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Common codes include invalid_token, too_many_requests, token_mismatched, api_not_implemented, and api_error. Log the full error object with trace_id, but show a short message in the UI. If you retry, create a new local attempt record so you can tell which task_id produced which callback.

A practical integration shape

A minimal database table might look like this:

video_jobs
- id
- task_id
- trace_id
- model
- prompt
- first_image_url
- callback_url
- state
- video_url
- created_at
- finished_at

The key idea is simple: treat video generation as a job, not a one-off request. Submit the prompt, store the returned task_id, and let the callback update the final video_url when it arrives.

If you want the full field reference and original examples, read the Hailuo Videos Generation API documentation: https://platform.acedata.cloud/documents/hailuo-videos-generation-integration

A Practical Guide to the Ace Data Cloud Python SDK

Germey — Wed, 19 Aug 2026 01:13:04 +0000

If your AI prototype has grown from one curl command into a small service, the next pain point is usually not the model — it is handling retries, streaming, async calls, task results, and errors without filling your codebase with one-off HTTP wrappers.

The Ace Data Cloud Python SDK is designed for that middle ground: you still call familiar API shapes such as chat completions and image generation, but you get a Python client with synchronous and asynchronous modes, SSE streaming support, retries, typed exceptions, and plain dict responses.

This guide turns the Python SDK documentation into a practical setup you can reuse in a CLI tool, FastAPI backend, automation script, or internal agent service.

What you can do

The acedatacloud package wraps services on api.acedata.cloud into typed methods. The documentation calls out examples such as:

client.openai.chat.completions.create(...)
client.images.generate(...)
client.search.google(...)

Under the hood it is built on httpx. The SDK supports SSE streaming, automatic retries, typed exceptions, and pydantic-style validation behavior, while response bodies are returned as regular Python dict objects.

That last part is worth noticing if you are migrating from openai-python: the docs explicitly note that the response body uniformly returns dict, not a pydantic model.

Install and prepare the token

Install the SDK from PyPI:

pip install acedatacloud
# or uv add / poetry add

If you use the X402 payment path instead of the API token path, the documentation lists a separate package:

pip install acedatacloud-x402

For the normal token-based path, export your token in the shell:

export ACEDATACLOUD_API_TOKEN={token}

The SDK reads ACEDATACLOUD_API_TOKEN automatically when you construct a client without passing api_token. The docs also mention a common repository convention where teams store ACEDATACLOUD_API_KEY; in that case, pass it explicitly:

import os
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

Call chat completions synchronously

A simple synchronous request is the best smoke test because it verifies authentication, model routing, and response parsing in one call.

import os, time, json
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_SDK_OK"}],
    max_tokens=20,
    temperature=0,
)

print("elapsed_ms", int((time.time() - t0) * 1000))
print("id", res["id"])
print("model", res["model"])
print("content", res["choices"][0]["message"]["content"])
print("usage", json.dumps({k: v for k, v in res["usage"].items()
                            if k in ("prompt_tokens", "completion_tokens", "total_tokens")}))

Because res is a dict, you access fields with normal dictionary indexing. The example also prints usage, which is useful in real services for logging token consumption alongside your own request ID.

In production, I would wrap this in a small function that accepts messages, model, and max_tokens, then logs res["id"] plus your user or job identifier. That gives you a clean trail for debugging later.

Stream responses for UI feedback

When stream=True, the SDK returns a regular generator. Each yielded item is a parsed chunk dictionary following the OpenAI SSE format.

import os, time
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
first_chunk_ms = None
chunks = 0
collected = []

for chunk in client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count from 1 to 5, separated by single spaces, no extra text."}],
    max_tokens=30,
    temperature=0,
    stream=True,
):
    if first_chunk_ms is None:
        first_chunk_ms = int((time.time() - t0) * 1000)
    chunks += 1
    delta = (chunk.get("choices") or [{}])[0].get("delta", {}).get("content")
    if delta:
        collected.append(delta)

print("first_chunk_ms", first_chunk_ms)
print("chunks", chunks)
print("collected", "".join(collected).strip())

This pattern maps nicely to web apps: read each delta, forward it to your frontend SSE endpoint, and keep the final joined text for persistence or audit logs.

Use the async client in services

For FastAPI, aiohttp, or any asyncio service, use AsyncAceDataCloud. The API is symmetrical, but I/O methods return coroutines.

import os, asyncio, time
from acedatacloud import AsyncAceDataCloud

async def main():
    client = AsyncAceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])
    t0 = time.time()
    res = await client.openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_ASYNC_OK"}],
        max_tokens=20,
        temperature=0,
    )
    print("elapsed_ms", int((time.time() - t0) * 1000))
    print("id", res["id"])
    print("content", res["choices"][0]["message"]["content"])
    await client.close()

asyncio.run(main())

The docs recommend explicitly closing the async client to shut down the connection pool. In a long-running service, create the client once during startup and close it once during shutdown rather than creating a new client per request.

Generate an image with `images.generate`

The Python SDK also exposes image generation. The documentation includes a NanoBanana example and notes that NanoBanana is synchronous, so you should not pass wait; the call blocks until the upstream returns 200.

import os, time
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
res = client.images.generate(
    provider="nano-banana",
    model="nano-banana",
    prompt="A minimalist logo of a yellow banana on a white background, flat design",
)

print("elapsed_ms", int((time.time() - t0) * 1000))
print("task_id", res.get("task_id"))
print("trace_id", res.get("trace_id"))

data = res.get("data") or []
if data:
    print("image_url", data[0].get("image_url"))

For longer-running asynchronous services such as Midjourney, Sora, Veo, and Suno, the docs point to task polling with wait=True or TaskHandle.wait().

Handle errors deliberately

The SDK includes typed exceptions such as AuthenticationError, RateLimitError, and ValidationError.

from acedatacloud import AceDataCloud
from acedatacloud import AuthenticationError, RateLimitError, ValidationError

bad = AceDataCloud(api_token="definitely-not-a-real-token")

try:
    bad.openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
        max_tokens=5,
    )
except AuthenticationError as err:
    print("err_class", type(err).__name__)
    print("status", err.status_code)
    print("code", err.code)
except RateLimitError as err:
    print("rate limited:", err.code)
except ValidationError as err:
    print("bad request:", err.code, err.message)

A useful production rule is to treat these differently: authentication errors should alert configuration owners, rate limits should trigger backoff or queueing, and validation errors should usually be fixed before retrying.

Configure timeouts, retries, and base URLs

The documented client options include api_token, base_url, platform_base_url, timeout, max_retries, and custom headers:

from acedatacloud import AceDataCloud

client = AceDataCloud(
    api_token="...",
    base_url="https://api.acedata.cloud",
    platform_base_url="https://platform.acedata.cloud",
    timeout=300.0,
    max_retries=2,
    headers={"x-app": "my-service/1.0"},
)

One migration footnote from the docs: Python SDK timeout values and task polling values are in seconds, while the TypeScript SDK uses milliseconds.

A simple service shape

For most projects, I would start with three files:

settings.py reads ACEDATACLOUD_API_TOKEN or your explicit secret name.
ai_client.py creates one AceDataCloud or AsyncAceDataCloud instance.
Feature code calls small wrapper functions for chat, streaming, or image generation.

That keeps the SDK boundary obvious and makes it easy to swap sync for async later.

Read the full Python SDK documentation here: https://platform.acedata.cloud/documents/sdk-python

How to Add Remote MCP Tools to Claude Code Without Leaving Your Terminal

Germey — Mon, 17 Aug 2026 01:07:32 +0000

When you are already using Claude Code for day-to-day development, the next bottleneck is often not code generation itself, but all the side tasks around it: searching, preparing visuals, creating demo assets, or shortening links without breaking your flow.

This guide walks through a practical setup: adding remote MCP servers to Claude Code so the assistant can call external tools from the same terminal session where you write and review code.

What you can do

Claude Code is Anthropic's command-line programming assistant. With MCP servers attached, it can still help with coding and refactoring, but it can also reach out to tool-specific services during a task.

The source documentation lists several managed remote MCP servers, including:

https://suno.mcp.acedata.cloud/mcp for music workflows
https://midjourney.mcp.acedata.cloud/mcp for image generation and editing workflows
https://flux.mcp.acedata.cloud/mcp for image workflows
https://seedream.mcp.acedata.cloud/mcp for image workflows
https://nanobanana.mcp.acedata.cloud/mcp for Gemini-driven image editing workflows
https://luma.mcp.acedata.cloud/mcp for video workflows
https://veo.mcp.acedata.cloud/mcp for video workflows
https://seedance.mcp.acedata.cloud/mcp for video workflows
https://serp.mcp.acedata.cloud/mcp for search workflows
https://shorturl.mcp.acedata.cloud/mcp for shortening links

The useful part is not that these exist as separate products. The useful part is that you can wire only the servers you need into Claude Code and then ask for a complete workflow in plain language.

How it works

Claude Code can register a remote MCP server with claude mcp add. The configuration uses:

a server name, such as serp or shorturl
--transport http
the remote MCP URL
an HTTP authorization header: Authorization: Bearer <token>

A minimal command looks like this:

claude mcp add serp --transport http https://serp.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

Two details are worth calling out.

First, -H must be uppercase because lowercase -h means help. Second, if you do not pass a scope, Claude Code uses the default local scope, which only applies in the current directory. If you want the same server available across projects, add -s user. If you want a project-level setup, use a project configuration file instead.

After adding one or more servers, check what Claude Code sees:

claude mcp list

You should see the servers you registered as HTTP MCP servers.

Option 1: add only the tools you need

For most developers, I would start with a small set rather than registering every server at once. For example, if you are writing technical posts from your terminal, search and short links are enough:

claude mcp add serp --transport http https://serp.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

claude mcp add shorturl --transport http https://shorturl.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

Then, inside Claude Code, you can ask for a workflow like:

Search for recent AI video generation trends, summarize the useful references, draft a technical outline, and shorten the key links.

That is a good fit for MCP because the assistant can combine reasoning, web search, and link handling without you copying data between browser tabs.

Option 2: keep project MCP config in `.mcp.json`

If the workflow belongs to a repository, you can define MCP servers in a .mcp.json file at the project root:

{
  "mcpServers": {
    "serp": {
      "type": "http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    },
    "shorturl": {
      "type": "http",
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The project-level file is useful when a team wants the same MCP names and URLs. Do not commit real tokens to a public repository. In practice, keep .mcp.json out of Git or replace secrets with environment-specific values that each developer fills in locally.

The documentation also notes that project-level .mcp.json takes precedence over the global Claude configuration. That makes it a reasonable place to encode repository-specific tool choices while still allowing personal global defaults elsewhere.

A realistic builder workflow

Here is a workflow I would actually use while maintaining a developer-facing project:

Ask Claude Code to inspect a README or docs folder.
Use search via the serp MCP server to find current references for a section that depends on recent ecosystem behavior.
Ask Claude Code to rewrite the section with citations or summarized links.
Use shorturl only for links that will be pasted into release notes or social posts.
Run claude mcp list if a tool is not being called as expected.

For more asset-heavy work, you could add image, music, or video MCP servers later, but the operational pattern stays the same: register the HTTP endpoint, pass the Authorization header, and let Claude Code call the tool when the task requires it.

Troubleshooting checklist

If a server is not working, start with the boring checks:

Run claude mcp list and confirm the server is present.
Remove and re-add the server if the URL or header is wrong.
Confirm you used uppercase -H.
Check whether the server was added locally, globally with -s user, or through project .mcp.json.
Make sure you did not paste a placeholder token by mistake.

The nice thing about this setup is that it is reversible. You can start with one MCP server, validate the workflow, and add more only when they remove real friction.

If you want the complete list of remote MCP URLs and the broader Claude Code examples, the original Ace Data Cloud guide is here: https://platform.acedata.cloud/documents/claude-code-mcp-all

How to Use an OpenAI-Compatible Endpoint in WorkBuddy

Germey — Sun, 16 Aug 2026 01:05:17 +0000

If you use a desktop AI workspace for real coding or office automation, the annoying part is rarely the chat UI. It is model routing: one task wants a long-context model, another wants a reasoning model, and another just needs a fast OpenAI-compatible chat endpoint.

This guide walks through a practical setup for using Ace Data Cloud as an OpenAI-compatible provider inside WorkBuddy, the desktop AI workspace from the Tencent CodeBuddy family. The goal is not to replace WorkBuddy's built-in models. It is to add your own custom model entries so you can switch between model families from the same WorkBuddy model picker.

What you can do

WorkBuddy supports custom models through an "OpenAI compatible protocol API" flow. Ace Data Cloud exposes chat-completion endpoints that match that shape, so the setup is mostly a matter of entering the right interface address, API key, and model name.

The document lists these interface addresses:

Model family	Interface address	Example model IDs
Claude / general entry	`https://api.acedata.cloud/v1/chat/completions`	`claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001`
GPT	`https://api.acedata.cloud/openai/chat/completions`	`gpt-5.6-sol`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.2`, `gpt-4o`, `o3`
Gemini	`https://api.acedata.cloud/gemini/chat/completions`	`gemini-3.1-pro`, `gemini-3.0-pro`, `gemini-3.5-flash`
Grok	`https://api.acedata.cloud/grok/chat/completions`	`grok-4`, `grok-3`
Kimi	`https://api.acedata.cloud/kimi/chat/completions`	`kimi-k3`, `kimi-k2.6`, `kimi-k2.5`
GLM	`https://api.acedata.cloud/glm/chat/completions`	`glm-5.1`, `glm-4.7`, `glm-4.6`
DeepSeek	`https://api.acedata.cloud/deepseek/chat/completions`	`deepseek-r1`, `deepseek-v3`, `deepseek-v4-flash`

The most convenient path is the general entry:

https://api.acedata.cloud/v1/chat/completions

According to the guide, /v1/chat/completions can route to different model IDs, not only Claude. If you prefer separate entries per model family, use one of the family-specific addresses above.

How it works in WorkBuddy

Open WorkBuddy and go to Settings → Models. In the Custom Models area, click Add Model. The add-model dialog is where the important mapping happens:

WorkBuddy field	Value to enter
Provider	`Custom`
Interface Address	For example, `https://api.acedata.cloud/v1/chat/completions`
API KEY	Your Ace Data Cloud API Token
Model Name	A real model ID, such as `claude-opus-4-8`, `gpt-5.5`, or `gemini-3.1-pro`

The interface address should include the full /chat/completions path. The guide notes that WorkBuddy validates the path according to OpenAI standards when Custom Protocol is off, and Ace Data Cloud's entry is already the complete standard path.

A minimal OpenAI-style request against the general endpoint looks like this:

curl -X POST "https://api.acedata.cloud/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {
        "role": "user",
        "content": "Review this function and suggest a safer implementation."
      }
    ]
  }'

The exact request is useful for sanity-checking the same endpoint and model name you put into WorkBuddy. If the model name is wrong, the document says the Ace Data Cloud gateway will reject the request and WorkBuddy will surface a 4xx error.

Choosing the advanced switches

WorkBuddy exposes several capability switches for custom models. These are not decoration; they tell the client how to treat the model in the UI.

Tool Calling declares that the model supports function calling or tools. The guide says mainstream Ace Data Cloud models such as Claude, GPT, Gemini, Grok, Kimi, and DeepSeek support this, so it can be enabled when your chosen model supports tools.

Image Input is for multimodal image input. Enable it only for model IDs that support multimodal input, such as the examples named in the document: claude-opus-4-8, gpt-5.5, or gemini-3.1-pro.

Inference Mode is for models with a visible reasoning or thinking process. The guide names o3, deepseek-r1, gemini-3.1-pro, and grok-4 as examples where this may apply.

Custom Protocol should stay off for this setup. With it off, WorkBuddy validates and uses the standard /chat/completions behavior; Ace Data Cloud's endpoint already matches that expectation.

For context-window dropdowns, the document recommends leaving both Input and Output as Use Provider Default, so WorkBuddy uses the upstream model's window configuration.

Adding more than one model

A useful pattern is to add multiple WorkBuddy custom model entries that share the same API key but use different model IDs.

For example, you might create:

Provider: Custom
Interface Address: https://api.acedata.cloud/v1/chat/completions
API KEY: YOUR_API_TOKEN
Model Name: claude-opus-4-8

Then repeat the same flow for:

Provider: Custom
Interface Address: https://api.acedata.cloud/openai/chat/completions
API KEY: YOUR_API_TOKEN
Model Name: gpt-5.5

After saving, both models appear under WorkBuddy's Custom Models group. That makes the model decision a per-task choice instead of a one-time workspace decision.

Troubleshooting checklist

If WorkBuddy returns an error, check these items first:

The interface address includes /chat/completions.
Custom Protocol is off.
The model name exactly matches a model ID supported by the selected endpoint.
The API key is the Ace Data Cloud API Token from your console.
Capability switches match the selected model; for example, do not enable image input for a text-only model.

WorkBuddy's own documentation says custom model configuration, including the API key, is stored locally in workbuddy/models.json and is not uploaded to the cloud. WorkBuddy acts as the communication link that forwards your input to the configured API address.

If you want the source configuration table and screenshots, the full Ace Data Cloud WorkBuddy setup guide is here: https://platform.acedata.cloud/documents/development_workbuddy

A Practical Guide to Running OpenCode with an OpenAI-Compatible Provider

Germey — Sat, 15 Aug 2026 01:10:09 +0000

If you use a terminal coding agent every day, one practical problem shows up quickly: how do you keep model access reproducible, project-friendly, and easy to verify without changing the way you work?

OpenCode is a terminal-first coding agent from the SST team. It can read code, modify files, run commands, explain errors, and help with day-to-day development tasks from your shell. The useful part for builders is that OpenCode supports custom model providers, so you can point it at an OpenAI-compatible endpoint while keeping the normal opencode command and TUI workflow.

This guide walks through configuring OpenCode to use Ace Data Cloud as a custom provider through its OpenAI Chat Completions-compatible proxy.

What you can do

After the setup, your workflow stays familiar:

run opencode inside a project and choose a model from /models
run one-off tasks with opencode run
keep your API token out of the JSON config by using an environment variable
expose only the model IDs you want OpenCode to use
use either a global config or a project-level config depending on the repository

The key values from the source guide are:

Base URL: https://api.acedata.cloud/v1
Chat Completions endpoint used under the hood: https://api.acedata.cloud/v1/chat/completions
Provider key used in the example: provider.acedatacloud
API token environment variable: ACEDATACLOUD_API_KEY
Authorization format: Authorization: Bearer <token>
Model name format in OpenCode: acedatacloud/<model>

How it works

OpenCode reads opencode.json at startup. The documented load order is:

global config: ~/.config/opencode/opencode.json
a custom config file pointed to by OPENCODE_CONFIG
project config: opencode.json in the project root, up to the Git root

Later config overrides earlier config. That makes it reasonable to keep a safe global provider definition and still customize models for a specific repository.

For this integration, OpenCode uses the Vercel AI SDK adapter @ai-sdk/openai-compatible. When you select a model such as acedatacloud/gpt-5-mini, OpenCode resolves the acedatacloud provider block, reads options.baseURL, resolves {env:ACEDATACLOUD_API_KEY}, and sends an OpenAI Chat Completions-format request to /v1/chat/completions with a bearer token.

No local proxy process is required. No wrapper CLI is required. You still run OpenCode normally; the configuration changes only the underlying API target and model list.

Install OpenCode

OpenCode supports macOS, Linux, Windows, and WSL. On macOS, Linux, or WSL, the guide lists this one-line installer:

curl -fsSL https://opencode.ai/install | bash

If you prefer package managers, the documented alternatives are:

brew install sst/tap/opencode
npm install -g opencode-ai

On Windows, you can use:

winget install sst.opencode

After installing, reopen your terminal and verify the command is available:

opencode --version

If you see command not found, the current shell probably has not loaded the new PATH yet. Close and reopen the terminal. On macOS with Homebrew, you can also check the binary path with which opencode.

Keep the token out of your config file

First, put your Ace Data Cloud API token into an environment variable:

export ACEDATACLOUD_API_KEY="{token}"

Replace {token} with the token from your console. Put the line in ~/.zshrc, ~/.bashrc, or ~/.bash_profile, then reload it:

source ~/.zshrc

A subtle issue: if your token lives in a .env file as ACEDATACLOUD_API_KEY=... without export, a plain source .env only creates a shell variable. Child processes such as OpenCode may not see it. Use this instead:

set -a && source .env && set +a

The goal is for OpenCode to resolve {env:ACEDATACLOUD_API_KEY} when it starts.

Register Ace Data Cloud as a provider

Create the global config file if it does not exist:

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

Then add a provider block like this:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "acedatacloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ace Data Cloud",
      "options": {
        "baseURL": "https://api.acedata.cloud/v1",
        "apiKey": "{env:ACEDATACLOUD_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "claude-haiku-4-5-20251001": { "name": "Claude Haiku 4.5" },
        "claude-opus-4-7": { "name": "Claude Opus 4.7" },
        "gpt-5": { "name": "GPT-5" },
        "gpt-5-mini": { "name": "GPT-5 mini" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "deepseek-v3.2-exp": { "name": "DeepSeek V3.2 Exp" }
      }
    }
  }
}

The important pieces are provider.acedatacloud as the local provider ID, @ai-sdk/openai-compatible as the adapter, https://api.acedata.cloud/v1 as the base URL, and {env:ACEDATACLOUD_API_KEY} as the token placeholder. The models object is the list OpenCode exposes under the provider.

Verify and run a smoke test

List the registered models:

opencode models acedatacloud

With the example config, the output should include:

acedatacloud/claude-haiku-4-5-20251001
acedatacloud/claude-opus-4-7
acedatacloud/claude-sonnet-4-6
acedatacloud/deepseek-v3.2-exp
acedatacloud/gemini-2.5-pro
acedatacloud/gpt-5
acedatacloud/gpt-5-mini

Now run a simple one-off task:

opencode run --model acedatacloud/claude-sonnet-4-6 "Reply: Hello from AceData via OpenCode."

The documented test output is:

> build · claude-sonnet-4-6

Hello from AceData via OpenCode.

For interactive work, move into a project and start the TUI:

cd /path/to/your/project
opencode

Then use /models to pick a configured model.

Troubleshooting notes

If opencode models acedatacloud does not show your provider, OpenCode probably did not read the config file. Restart the TUI after edits, or run with --print-logs --log-level INFO and check which config path is loaded.

If you get 401 Unauthorized, check that ACEDATACLOUD_API_KEY is exported in the current shell. If opencode debug config shows "Authorization": "Bearer ", the placeholder resolved to an empty value.

If OpenCode reports Model not found: acedatacloud/..., make sure that model ID is present as a key under provider.acedatacloud.models.

For MCP-heavy sessions, the guide notes that OpenAI-series models such as gpt-5 or gpt-5-mini are a good first choice when many MCP tools are mounted, while Claude models work normally for plain conversation.

If you want the full reference, read the original OpenCode Terminal Setup Guide.

How to Use Claude Code in VS Code with a Project-Local API Configuration

Germey — Fri, 14 Aug 2026 01:03:41 +0000

You want Claude Code inside VS Code, but you also want the configuration to be explicit, project-scoped, and safe to keep out of source control.

What you can do

Claude Code is a programming agent from Anthropic. In VS Code, the Claude Code extension gives you a native editor experience: a sidebar entry, a panel for asking coding questions, and the same underlying settings model used by the terminal CLI.

The useful part for a team project is that you do not have to put credentials into a shared repository-level config. You can create a local file under the project root, configure the API endpoint there, restart VS Code, and keep the token out of Git.

The Ace Data Cloud setup described here uses the Claude Code extension with these documented values:

project-local settings file: .claude/settings.local.json
base URL: https://api.acedata.cloud
auth token variable: ANTHROPIC_AUTH_TOKEN
automatic compaction window variable: CLAUDE_CODE_AUTO_COMPACT_WINDOW
recommended compaction value from the guide: 850000

That is enough to make VS Code launch Claude Code with the project-specific environment you expect.

How it works

The VS Code extension and the terminal CLI read the same Claude Code settings. Instead of signing in through the official Anthropic account flow in the extension, you point Claude Code at the Ace Data Cloud proxy API by setting environment variables in Claude Code's settings file.

For a single project, create this file:

.claude/settings.local.json

Then put the following JSON inside it:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "850000"
  }
}

Replace {token} with the API token you copied from the Ace Data Cloud console. Keep the file local to the project and avoid committing it. The guide specifically recommends using settings.local.json for the current project and adding that path to .gitignore.

The CLAUDE_CODE_AUTO_COMPACT_WINDOW setting does not change the model's context limit. It sets the trigger window for automatic compression to around 850,000 tokens, leaving room for tool results and final answers.

Step 1: Install the Claude Code extension

Open the VS Code extension marketplace and search for Claude Code. Install the Claude Code extension, then accept the trust prompt shown by VS Code.

After installation, you should see a Claude Code entry in the VS Code sidebar. Opening it may lead you toward an official login prompt. For this workflow, you can skip that and configure the proxy API through the local settings file instead.

Step 2: Add project-local settings

From your project root, create the .claude directory and the local settings file:

mkdir -p .claude
cat > .claude/settings.local.json <<'JSON'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "850000"
  }
}
JSON

Now edit the file and replace {token} with your real API token.

This pattern is intentionally boring: the base URL is visible, the credential is isolated, and the config is easy to remove when you no longer need it.

Step 3: Keep credentials out of Git

Add the local settings file to .gitignore:

printf '\n.claude/settings.local.json\n' >> .gitignore

Do not put the real token into .claude/settings.json if that file is shared with the team. The documented project-local file is a better place for personal or machine-specific credentials.

One more gotcha from the guide: if the environment that launches VS Code already has an old ANTHROPIC_API_KEY, unset it first. Do not treat an empty string as cleanup; actually remove the variable from that environment.

For example, if you launch VS Code from a shell:

unset ANTHROPIC_API_KEY
code .

Step 4: Restart or reload VS Code

After changing the settings file, restart or reload VS Code so the Claude Code extension reads the new environment values.

Open the Claude Code panel and ask a small project-aware question, such as:

Read the package scripts and explain how to run the test suite.

That is a good first prompt because it checks whether the extension can see your workspace and respond in context without making any destructive edits.

When to use project-local config vs global config

Use .claude/settings.local.json when you want one repository to use this setup and you do not want to affect every other project on your machine.

Use ~/.claude/settings.json only when you deliberately want the same configuration to apply across all projects. Even then, be careful with credential storage and with any older environment variables that might override what you expect.

For me, the local file is the safer default: it is visible while you are working on the project, easy to audit, and easy to keep out of commits.

A small checklist before you start editing code

Before asking Claude Code to modify files, I would check four things:

.claude/settings.local.json exists in the project root.
ANTHROPIC_BASE_URL is exactly https://api.acedata.cloud.
ANTHROPIC_AUTH_TOKEN is set to your token, not a placeholder.
.claude/settings.local.json is ignored by Git.

Once those are true, you can use the Claude Code panel in VS Code as your normal coding assistant: ask it to explain code, inspect errors, propose diffs, or help navigate an unfamiliar repository.

The original Ace Data Cloud guide is here if you want to compare the exact setup notes: Claude Code VS Code setup guide.

How to Run Claude Code from Your Terminal with an API Proxy

Germey — Thu, 13 Aug 2026 01:07:38 +0000

You want Claude Code to behave like a normal local CLI tool, but you also want the API connection to be explicit, reproducible, and easy to verify across projects.

What you can do

Claude Code is a terminal-based coding agent. Once it is installed, you can run claude inside a project directory and ask it to read code, modify files, run commands, explain errors, or inspect a recent diff.

The useful part for builders is that Claude Code already reads standard environment variables before it sends requests. That means you can keep the native claude workflow while pointing the underlying API traffic at Ace Data Cloud:

Base URL: https://api.acedata.cloud
Auth variable: ANTHROPIC_AUTH_TOKEN
Optional local project config: .claude/settings.local.json
Optional context compaction trigger: CLAUDE_CODE_AUTO_COMPACT_WINDOW="850000"

The rest of your workflow stays familiar: open a terminal, cd into a repository, run claude, and ask for help.

How it works

Claude Code uses the Anthropic Messages API protocol. The terminal app decides where to send requests by reading ANTHROPIC_BASE_URL and authenticates with ANTHROPIC_AUTH_TOKEN.

When ANTHROPIC_BASE_URL is set to https://api.acedata.cloud, Claude Code sends requests to Ace Data Cloud. Ace Data Cloud checks the API token, routes the request to an available Claude Code service channel, and records usage after the request completes.

No local proxy process is required. No wrapper CLI is required. You still run the official claude command; the only change is the API target and token.

Step 1: Install the Claude Code CLI

Claude Code supports macOS, Linux, Windows, and WSL. The native installer is the simplest path because it installs the claude command and handles updates.

On macOS, Linux, or WSL:

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

On Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If you prefer npm and already have Node.js 18 or higher:

npm install -g @anthropic-ai/claude-code

Then reopen your terminal and check the command:

claude --version

If the shell says command not found, reopen the terminal again or inspect the PATH message printed by the installer.

Step 2: Configure it globally for your shell

If you want every project on your machine to use the same API route, put the configuration in your shell startup file: ~/.zshrc, ~/.bashrc, or ~/.bash_profile.

export ACEDATACLOUD_API_TOKEN="{token}"
export ANTHROPIC_BASE_URL="https://api.acedata.cloud"
export ANTHROPIC_AUTH_TOKEN="$ACEDATACLOUD_API_TOKEN"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="850000"

Replace {token} with your API token from the Ace Data Cloud console. The CLAUDE_CODE_AUTO_COMPACT_WINDOW value sets the automatic compression trigger window to about 850,000 tokens. It reserves room for tool results and final answers; it does not change the model context limit.

Reload the shell config:

source ~/.zshrc

Use the matching file name if you configured Bash instead of Zsh.

Step 3: Or configure only one repository

For team projects, I usually prefer project-local configuration with a personal ignored file. Create .claude/settings.local.json in the repository root:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "850000"
  }
}

This only affects the current project. The same file is also read when the project is opened with the Claude Code VS Code extension.

Do not commit personal credentials. Add this file to .gitignore:

.claude/settings.local.json

If your shell already has an old ANTHROPIC_API_KEY, unset it in the same environment where you launch Claude Code or VS Code:

unset ANTHROPIC_API_KEY

The important detail is to actually unset it, not set it to an empty string. After changing this, restart Claude Code. For VS Code, reload the window.

Step 4: Start a session and verify the route

From a project directory:

cd /path/to/your/project
claude

A first prompt can be simple:

Explain the directory structure of this project

For a one-off task, pass the prompt directly:

claude "Help me check the recent git diff for possible bugs"

If you want Claude Code to print the result and exit, use -p:

claude -p "Summarize the purpose of README.md"

Inside the interactive Claude Code interface, run:

/status

You should see the auth source and base URL, including:

Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://api.acedata.cloud

If the base URL is not https://api.acedata.cloud, the current terminal probably did not load the expected shell config, or a project-level config is overriding it.

Optional: choose model tiers explicitly

Claude Code can select models by task type, but the documented environment variables let you set defaults:

export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-8"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"

Use these only if you know you want consistent model choices. Otherwise, the default Claude Code selection is a reasonable starting point.

A practical habit

Keep global config for personal machines and use .claude/settings.local.json when a repository needs a predictable setup. In both cases, verify with /status before doing serious work. That one check catches most misconfigured shells, stale login state, and accidental credential conflicts.

For the full Ace Data Cloud reference, see the Claude Code terminal setup guide: https://platform.acedata.cloud/documents/claude-code-terminal-integration

How to Fetch the Official MP4 for a Suno Track from an API

Germey — Wed, 12 Aug 2026 01:15:06 +0000

If your app generates music, the next practical problem is usually distribution: you may have a song ID, but your UI, CMS, or social workflow often needs a shareable MP4 asset.

This guide shows a small but useful backend pattern: take a Suno-generated audio_id, call the Suno MP4 endpoint through Ace Data Cloud, and store the returned data.video_url for playback, publishing, or downstream processing.

The API in this document is intentionally simple. That makes it a good example of how to wrap a media-generation step with a clean service boundary: one input, one POST request, one output URL.

What you can do

The Suno MP4 API lets you obtain the official generated MP4 link for a generated music track.

The core details are:

Endpoint: POST https://api.acedata.cloud/suno/mp4
Request format: JSON
Auth header: authorization: Bearer {token}
Content header: content-type: application/json
Accept header: accept: application/json
Required body field: audio_id
Output field to persist: data.video_url

The request body has only one input parameter:

{
  "audio_id": "275113ab-fe5c-4bca-a33c-0cca96b39fa6"
}

That simplicity is useful in production. You can treat MP4 fetching as a deterministic enrichment step after music generation: once a track has an official song ID, your worker asks for the corresponding MP4 and saves the returned URL.

How it works

A typical backend flow looks like this:

Your app already has a Suno audio_id from an earlier generation step.
A worker calls POST /suno/mp4 with that ID.
The API responds with success, task_id, trace_id, and data.video_url.
Your app stores data.video_url next to the track record.
The frontend uses that URL for preview, download, or a publishing workflow.

Here is the documented Python request:

import requests

url = "https://api.acedata.cloud/suno/mp4"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "275113ab-fe5c-4bca-a33c-0cca96b39fa6"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

A successful response looks like this:

{
  "success": true,
  "task_id": "03ae7cca-c3a2-40a0-98b2-8f33426af438",
  "trace_id": "848d8d5a-d6bb-4e16-bb29-768c22cf1b3b",
  "data": {
    "video_url": "https://cdn1.suno.ai/275113ab-fe5c-4bca-a33c-0cca96b39fa6.mp4"
  }
}

The field you normally want is data.video_url. task_id and trace_id are also worth logging because they make support and debugging much easier if a job behaves unexpectedly.

A curl version for workers and scripts

For a small queue worker, cron job, or shell-based test, the same request can be expressed with curl:

curl -X POST "https://api.acedata.cloud/suno/mp4" \
  -H "accept: application/json" \
  -H "authorization: Bearer {token}" \
  -H "content-type: application/json" \
  -d '{
    "audio_id": "275113ab-fe5c-4bca-a33c-0cca96b39fa6"
  }'

If I were integrating this into a service, I would keep the function tiny:

def fetch_suno_mp4(audio_id: str, token: str) -> str:
    response = requests.post(
        "https://api.acedata.cloud/suno/mp4",
        json={"audio_id": audio_id},
        headers={
            "accept": "application/json",
            "authorization": f"Bearer {token}",
            "content-type": "application/json",
        },
        timeout=60,
    )
    response.raise_for_status()
    body = response.json()
    return body["data"]["video_url"]

This keeps the rest of your codebase from knowing about endpoint paths or response shape. The rest of the app only asks for an MP4 URL.

Where this fits in a real product

A common media app pipeline might have records like this:

{
  "track_id": "internal_123",
  "audio_id": "275113ab-fe5c-4bca-a33c-0cca96b39fa6",
  "title": "late night demo",
  "mp4_url": null,
  "status": "audio_generated"
}

After calling the MP4 API, update the record:

{
  "track_id": "internal_123",
  "audio_id": "275113ab-fe5c-4bca-a33c-0cca96b39fa6",
  "title": "late night demo",
  "mp4_url": "https://cdn1.suno.ai/275113ab-fe5c-4bca-a33c-0cca96b39fa6.mp4",
  "status": "mp4_ready"
}

That small state transition unlocks a lot of product behavior: a preview button in an admin panel, a scheduled social post, an export queue, or a download link in a user dashboard.

Practical implementation notes

Because the request has only one business field, most production issues will come from surrounding concerns rather than request construction.

First, validate that audio_id exists before sending the request. If your generation step is asynchronous, do not call the MP4 endpoint until the track has an official generated song ID.

Second, do not expose your API token in frontend code. Keep the authorization header on the server side and let your backend return only the MP4 URL or your own signed asset reference.

Third, persist the full response metadata somewhere useful. Even if your main table only stores mp4_url, logging task_id and trace_id gives you a clean audit trail.

Finally, make the function idempotent at the application level. If a track already has an mp4_url, your worker can skip the call unless you explicitly want to refresh it.

A small API, but a useful boundary

The nice thing about this endpoint is that it does not try to do too much. It converts one known identifier, audio_id, into one useful media asset, data.video_url. That makes it easy to test, easy to retry, and easy to fit into an existing media pipeline.

For the original field names and sample response, see the Ace Data Cloud documentation: https://platform.acedata.cloud/documents/suno-mp4-integration

A Practical Guide to Adding Nano Banana Image Tools to Claude Desktop, VS Code, and Cursor

Germey — Mon, 10 Aug 2026 01:04:13 +0000

If your coding assistant can already read files, run commands, and reason about a project, the next useful step is often visual: generating mockups, editing product shots, or iterating on image assets without leaving the IDE.

What you can do

Nano Banana MCP is an MCP server for connecting image generation and image editing tools to AI clients such as Claude Desktop, VS Code, and Cursor. Once it is configured, the assistant can call a small set of image-focused tools during a normal conversation instead of forcing you to switch to a separate image UI.

The documented tool surface is intentionally compact:

nanobanana_generate_image — generate images from text prompts
nanobanana_edit_image — edit or combine existing images
nanobanana_get_task — query the status of one task
nanobanana_get_tasks_batch — query multiple task statuses

The server supports the nano-banana, nano-banana-2, and nano-banana-pro models. That makes it a good fit for builder workflows where you want to move from a text idea to an image, then keep refining that image in the same chat.

Typical examples from the integration guide include prompts like:

"Help me generate a watercolor landscape painting"
"Photoshop this clothing onto this person"
"Place this product in a café scene"
"Generate a high-quality portrait using the nano-banana-pro model"

Those examples are useful because they show the real shape of the workflow: the user describes the image task in natural language, and the MCP client routes the request to the available Nano Banana tool.

How it works

MCP, or Model Context Protocol, gives AI clients a standard way to call external tools. In this setup, the local MCP server is mcp-nanobanana-pro. Your client starts that command, passes an Ace Data Cloud token through the ACEDATACLOUD_API_TOKEN environment variable, and then exposes the Nano Banana tools to the assistant.

The basic installation path is:

pip install mcp-nanobanana-pro

If you prefer installing from source, the documented path is:

git clone https://github.com/AceDataCloud/NanoBananaMCP.git
cd NanoBananaMCP
pip install -e .

After installation, the command your client needs to run is:

mcp-nanobanana-pro

The important thing is not to hard-code secrets in prompts or project files you plan to commit. Treat ACEDATACLOUD_API_TOKEN like any other API token: keep it local, rotate it if needed, and avoid pasting it into public issues or screenshots.

Configure Claude Desktop

For Claude Desktop, edit the client configuration file. The documented locations are:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Add an MCP server named nanobanana:

{
  "mcpServers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "Your API Token"
      }
    }
  }
}

If you use uvx and do not want to install the package in advance, the guide also documents this version:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "Your API Token"
      }
    }
  }
}

Save the file, restart Claude Desktop, and start with a small request. For example, ask it to generate a simple icon concept or edit one existing image. A small first test makes it easier to verify that the server starts correctly and that the token is available to the process.

Configure VS Code or Cursor

For VS Code and Cursor, create .vscode/mcp.json in the project root:

{
  "servers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "Your API Token"
      }
    }
  }
}

The uvx version is similar:

{
  "servers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "Your API Token"
      }
    }
  }
}

This project-level setup is nice when the visual workflow belongs to a specific repository. For example, a frontend repo might use it for hero image drafts, empty-state illustrations, or product-placement experiments. A docs repo might use it to generate tutorial covers and diagrams. Because the MCP config lives with the workspace, the assistant has the right tool available where the work happens.

A practical workflow to try

Here is a simple builder-oriented loop:

Ask the assistant to draft a prompt for the image you need.
Run generation with nanobanana_generate_image.
Review the result in the chat or client output.
Ask for a targeted edit with nanobanana_edit_image.
Use nanobanana_get_task if the client needs to check task progress.

For example, in a product UI project you might say:

Generate a clean dashboard illustration for a dark-mode SaaS landing page. Use a minimal terminal panel, API cards, and a blue/green accent palette.

Then follow up with:

Edit the image so the API cards are less crowded and the terminal panel is more prominent.

That is where MCP feels useful: the same assistant that understands your implementation context can also help you iterate on visual assets.

Closing notes

Nano Banana MCP is not a replacement for design judgment, but it is a practical way to bring image generation and editing closer to where builders already work: Claude Desktop, VS Code, and Cursor. Start with a narrow use case, keep prompts specific, and treat the generated output as a draft you can refine.

The full setup reference is in the Ace Data Cloud Nano Banana MCP documentation: https://platform.acedata.cloud/documents/nano-banana-mcp

How to Build a Talking-Photo Lip Sync Pipeline with Kling and an API

Germey — Sun, 09 Aug 2026 01:03:52 +0000

If you have ever tried to turn a still portrait into a short narrated video, the hard part is usually not generating the face motion — it is keeping the mouth movement aligned with the voice without stitching together a fragile video pipeline.

This guide walks through a small, practical pipeline using the Kling Lip Sync API on Ace Data Cloud. The goal is simple: start with a Kling-generated 5s or 10s video, then drive the character's mouth with either an audio file or a short text prompt.

The useful part is that the lip sync step is just one JSON request, so you can wire it into a backend job, an internal content tool, or a prototype for digital-human narration without building a custom video stack.

What you can do

The endpoint is:

POST https://api.acedata.cloud/kling/lip-sync

It accepts application/json and returns application/json. You authenticate with a bearer token:

authorization: Bearer ${API_KEY}
content-type: application/json
accept: application/json

There are two generation modes:

audio2video: use an existing audio file to drive the mouth movement.
text2video: provide short text and a voice ID, and let the API generate the speech and lip sync together.

For the source video, you provide exactly one of these:

video_id: the ID of a Kling-generated video, such as one returned by /kling/videos with image2video.
video_url: a public URL to a video file.

The video_id path is convenient if you are already using Kling to animate a still image. The docs note that the video must be 5s or 10s and generated within the last 30 days. If you use video_url, the file must be .mp4 or .mov, no more than 100MB, 2–10 seconds long, 720p or 1080p, and between 720 and 1920 pixels in dimensions.

How it works

Think of the API as a second pass after you already have a short character video.

A complete talking-photo flow looks like this:

still image -> /kling/videos image2video -> video_id -> /kling/lip-sync -> video_url

The first step creates motion from an image. The second step replaces or aligns the mouth motion so the subject speaks naturally.

Here is the image-to-video step shown in the docs:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "kling-v2-1-master",
    "action": "image2video",
    "start_image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "prompt": "look at camera, natural",
    "duration": 5,
    "mode": "pro"
  }'

That request returns a video_id, which becomes the input to the lip sync call.

Option 1: drive the video with audio

Use audio2video when you already have a voiceover, a TTS file, or a recorded narration.

curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "audio2video",
    "video_id": "895055164389466178",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }'

For this mode, audio_url is required when audio_type is url, which is also the default. Supported audio formats are .mp3, .wav, .m4a, and .aac, with a maximum file size of 5MB.

A practical tip: keep the audio duration close to the video duration. The API can only work with the visual material you give it, so a 12-second narration is not a good fit for a 5-second clip.

Option 2: drive the video with text

Use text2video when you want to produce a short line directly from text.

curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "text2video",
    "video_id": "895055164389466178",
    "text": "Hi, long time no see. I am doing well, take care of yourself.",
    "voice_id": "genshin_vindi2",
    "voice_language": "en",
    "voice_speed": 1.0
  }'

In text2video, the required fields are:

text: the line to speak, up to 120 characters.
voice_id: the voice to use.

Optional voice controls include:

voice_language: zh or en, defaulting to zh.
voice_speed: from 0.8 to 2.0, with one decimal place.

This mode is useful for UI previews, short product explainers, onboarding clips, or any workflow where the script is generated dynamically and you do not want to manage separate audio files.

Handling the response

A successful synchronous response includes the task ID, the new Kling video ID, and the final video URL:

{
  "success": true,
  "task_id": "07a3ec65-9f7e-4a09-b7b7-282684082527",
  "video_id": "895055968777281546",
  "video_url": "https://platform2.cdn.acedata.cloud/kling/07a3ec65-9f7e-4a09-b7b7-282684082527.mp4",
  "duration": "4.966",
  "state": "succeed"
}

The returned video_url is the artifact you can show in your app, hand off to an editor, or queue for another processing step. The returned video_id is also reusable for later Kling operations such as another lip sync or extension step.

Async mode for production jobs

For a backend workflow, you probably do not want to hold a request open while a video job runs. The API supports async mode in two ways:

{
  "mode": "audio2video",
  "video_id": "895055164389466178",
  "audio_url": "https://your.cdn/voice.mp3",
  "async": true
}

You can also provide callback_url. Either option returns a task_id immediately. To poll, call /kling/tasks with:

{
  "action": "retrieve",
  "id": "<task_id>"
}

A good production pattern is to store the original request, the task_id, and the current state in your database. Then either process the callback or poll from a worker until the task reaches a terminal state.

A few guardrails I would add

Before sending a request, validate the constraints close to your UI or API boundary:

Require exactly one of video_id or video_url.
For text2video, reject text longer than 120 characters.
For audio2video, check that audio is no larger than 5MB.
Prefer clear, frontal, single-person videos.
Keep the script or audio length aligned with the clip length.

These small checks prevent the most common bad requests and make the workflow much easier to debug.

If you want the exact field table and the latest constraints, the full Ace Data Cloud doc is here: https://platform.acedata.cloud/documents/kling-lip-sync-integration

How to Build an Audio-Driven Talking Photo Workflow with Dreamina

Germey — Sat, 08 Aug 2026 01:13:49 +0000

Turning a portrait and a voice recording into a short talking video sounds like a “demo day” feature, but the production details matter: public asset URLs, audio length limits, async job handling, and error traces.

This guide walks through the Dreamina Video Generation API on Ace Data Cloud from a builder’s point of view. We will send a portrait image plus a driving audio file, receive a synchronized speaking video, and decide when to use callbacks or polling instead of waiting on one long HTTP request.

What you can do

The Dreamina Video Generation API is designed for audio-driven talking-photo generation. You provide a portrait image via image_url, a driving audio file via audio_url, and optional steering text via prompt. The endpoint generates a video where the person speaks with synchronized lips. The model defaults to omnihuman-1.5.

The core API shape is compact:

Endpoint: POST https://api.acedata.cloud/dreamina/videos
Authorization: Bearer <your API key>
Content-Type: application/json

The required request parameters are image_url and audio_url. Optional fields include model, prompt, mask_url, callback_url, and async.

The smallest useful request

Here is a minimal JSON request body:

{
  "model": "omnihuman-1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/voice.wav",
  "prompt": "Natural speaking expression, stable face, calm presenter style"
}

And here is the same call as cURL:

curl -X POST 'https://api.acedata.cloud/dreamina/videos' \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "omnihuman-1.5",
    "image_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/voice.wav",
    "prompt": "Natural speaking expression, stable face, calm presenter style"
  }'

The guide’s response example returns a platform-level task_id, a trace_id, and a nested data object with the upstream task and media URLs:

{
  "success": true,
  "task_id": "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": {
    "task_id": "362b4fed67bd11f1ad1100163e57d510",
    "status": "done",
    "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }
}

For an app, data.video_url is the artifact you show to the user. Keep trace_id in logs because it is useful when debugging failed or slow jobs.

Preparing the image and audio

The API is only as good as the assets you send it. For the image, use a clear, well-lit, front-facing portrait. The face should be unobstructed and reasonably large in the frame. This is the kind of constraint you should enforce in your UI copy before users upload anything.

For the audio, use a public mp3 or wav URL. The guide says to keep audio under 60 seconds, with 30 seconds or less recommended for 1080p and 60 seconds or less for 720p. Both image_url and audio_url must be reachable from the public internet.

That last point is easy to miss. A signed URL that expires too quickly, a private S3 object, or a localhost link will fail. In a production flow, upload the portrait and audio to durable public URLs before calling the API.

Synchronous, callback, or polling?

By default, the endpoint runs synchronously and returns the finished video. That is convenient for short tests, but video generation can take long enough that you may not want to keep a web request open.

The guide documents two async patterns. First, you can pass callback_url:

{
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/voice.mp3",
  "callback_url": "https://example.com/webhooks/dreamina-result"
}

With this pattern, the endpoint returns a task_id immediately and POSTs the result to your URL when ready.

Second, you can pass async: true:

{
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/voice.mp3",
  "async": true
}

With async: true, the endpoint returns a task_id immediately, and you poll the result with POST /dreamina/tasks using either task_id or trace_id.

A simple production pattern is: create a local job row with status pending, submit /dreamina/videos, store task_id and trace_id, show a pending state, and mark the job done when the webhook or polling result contains data.video_url.

Handling common failures

The documented errors are straightforward, but you should map them to actionable product states:

400 bad_request: missing or invalid parameters such as image_url or audio_url
401 authorization_missing or invalid_token: missing or invalid token
403 forbidden: insufficient balance or quota, or upstream not authorized
429 too_many_requests: rate limit exceeded
500 api_error: internal server error

The error response includes trace_id:

{
  "error": {
    "code": "bad_request",
    "message": "image_url is required (a public URL of a portrait image)"
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

In your client, branch on error.code, show a human-readable message, and always log trace_id.

A practical checklist

Before you ship a talking-photo feature, I would add these checks:

require a clear frontal portrait before upload
validate that audio is mp3 or wav and under the duration limit
upload both files to public URLs before calling the API
keep Authorization: Bearer <your API key> server-side
store task_id, trace_id, input URLs, and data.video_url
prefer callback_url or async: true for user-facing workflows

That gives you a small but reliable pipeline: portrait plus voice in, video_url out, and enough task metadata to debug what happened.

The maintained reference for fields, async behavior, and errors is here: https://platform.acedata.cloud/documents/dreamina-videos-integration

DEV Community: Germey

A Practical Guide to Music Generation in Claude Code with MCP

How to Build an Async Text-to-Video Workflow with a REST API

What you can do

Start with a text-to-video request

Add image-to-video without changing your pipeline

Use callbacks for production-style requests

Handle errors deliberately

A practical integration shape

A Practical Guide to the Ace Data Cloud Python SDK

What you can do

Install and prepare the token

Call chat completions synchronously

Stream responses for UI feedback

Use the async client in services

Generate an image with images.generate

Handle errors deliberately

Configure timeouts, retries, and base URLs

A simple service shape

How to Add Remote MCP Tools to Claude Code Without Leaving Your Terminal

What you can do

How it works

Option 1: add only the tools you need

Option 2: keep project MCP config in .mcp.json

A realistic builder workflow

Troubleshooting checklist

How to Use an OpenAI-Compatible Endpoint in WorkBuddy

What you can do

How it works in WorkBuddy

Choosing the advanced switches

Adding more than one model

Troubleshooting checklist

A Practical Guide to Running OpenCode with an OpenAI-Compatible Provider

What you can do

How it works

Install OpenCode

Keep the token out of your config file

Register Ace Data Cloud as a provider

Verify and run a smoke test

Troubleshooting notes

How to Use Claude Code in VS Code with a Project-Local API Configuration

What you can do

How it works

Step 1: Install the Claude Code extension

Step 2: Add project-local settings

Step 3: Keep credentials out of Git

Step 4: Restart or reload VS Code

When to use project-local config vs global config

A small checklist before you start editing code

How to Run Claude Code from Your Terminal with an API Proxy

What you can do

How it works

Step 1: Install the Claude Code CLI

Step 2: Configure it globally for your shell

Step 3: Or configure only one repository

Step 4: Start a session and verify the route

Optional: choose model tiers explicitly

A practical habit

How to Fetch the Official MP4 for a Suno Track from an API

What you can do

How it works

A curl version for workers and scripts

Where this fits in a real product

Practical implementation notes

A small API, but a useful boundary

A Practical Guide to Adding Nano Banana Image Tools to Claude Desktop, VS Code, and Cursor

What you can do

How it works

Configure Claude Desktop

Configure VS Code or Cursor

A practical workflow to try

Closing notes

How to Build a Talking-Photo Lip Sync Pipeline with Kling and an API

What you can do

How it works

Option 1: drive the video with audio

Option 2: drive the video with text

Handling the response

Async mode for production jobs

A few guardrails I would add

Generate an image with `images.generate`

Option 2: keep project MCP config in `.mcp.json`