DEV Community: Germey

A Practical Guide to Adding MCP Servers to Codex CLI

Germey — Fri, 11 Sep 2026 01:08:09 +0000

Codex CLI is great at working inside a repository, but sometimes the useful thing it needs is outside the repo: a fresh web search, an image tool, a short-link helper, or a media workflow that should be called as a tool instead of described in text.

That is where MCP is useful. Instead of asking a coding agent to explain how it would use an external capability, you wire that capability into the agent as a remote server. This guide walks through the practical configuration pattern for connecting Codex CLI to Ace Data Cloud MCP servers.

What you can do

Codex CLI uses the ~/.codex/config.toml configuration file for MCP server entries. Each remote MCP server gets a named section, a url, and an http_headers object containing the Bearer token.

The documented Ace Data Cloud MCP servers include:

Suno for music workflows: https://suno.mcp.acedata.cloud/mcp
Flux for image generation and editing: https://flux.mcp.acedata.cloud/mcp
Seedream for image generation and editing: https://seedream.mcp.acedata.cloud/mcp
NanoBanana for Gemini-driven image workflows: https://nanobanana.mcp.acedata.cloud/mcp
Luma for video workflows: https://luma.mcp.acedata.cloud/mcp
Veo for video workflows: https://veo.mcp.acedata.cloud/mcp
Seedance for video workflows: https://seedance.mcp.acedata.cloud/mcp
Serp for Google web, image, and news search: https://serp.mcp.acedata.cloud/mcp
ShortURL for single and batch short links: https://shorturl.mcp.acedata.cloud/mcp

You do not have to add everything. For a coding workflow, I would usually start with one search server and one artifact-oriented server, then add more only when the workflow actually needs them.

How it works

An MCP entry in Codex CLI is just TOML. The important pieces are the server name, the remote URL, and the Authorization header. The source guide shows this shape:

[mcp_servers.serp]
url = "https://serp.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

Replace yourToken with your Ace Data Cloud token, save the file, then restart Codex CLI so the MCP servers are loaded again.

For a small, practical setup, your ~/.codex/config.toml might start like this:

[mcp_servers.serp]
url = "https://serp.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

[mcp_servers.flux]
url = "https://flux.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

[mcp_servers.shorturl]
url = "https://shorturl.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

This gives the agent three different kinds of help: search for context, image tooling for visual artifacts, and short links for sharing outputs. The exact tool names available to Codex will come from the remote MCP servers after they load.

Keep the first configuration small

It is tempting to paste every server into the config file at once. The overview document does provide entries for Suno, Flux, Seedream, NanoBanana, Luma, Veo, Seedance, Serp, and ShortURL, but a smaller first pass is easier to test.

A good first test is search, because the expected behavior is easy to verify. After restarting Codex CLI, ask for something concrete like:

Use Serp to search for "OpenAI Codex CLI tutorial 2026" for the top 5 latest articles.

If Codex can see and call the MCP server, it should treat search as a tool call rather than guessing from its training data. That is the real value of this setup: the model stays in the coding loop, while current or specialized work moves to a tool.

Add creative tools only when the repo needs them

Once search works, add servers that match your actual project. If you are writing documentation, a useful workflow might be:

Use Flux to generate a GitHub PR cover image with the theme "Open Source Collaboration", 1280x640.

If you are preparing a demo, the source guide gives another example:

Use Suno to write a 45-second calm piano piece for developer tutorial BGM.

Those prompts are intentionally task-level. You are not hard-coding image or music parameters into your app; you are giving Codex an external capability it can call while you stay in the terminal.

A fuller config example

When you are ready to expand, append only the servers you need. The documented pattern is consistent across servers:

[mcp_servers.suno]
url = "https://suno.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

[mcp_servers.nanobanana]
url = "https://nanobanana.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

[mcp_servers.veo]
url = "https://veo.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

[mcp_servers.seedance]
url = "https://seedance.mcp.acedata.cloud/mcp"
http_headers = { "Authorization" = "Bearer yourToken" }

The same token is used in the Authorization header for each server. If something fails, first check the TOML syntax, the server URL, and whether the Bearer token was pasted correctly. Then restart Codex CLI again; configuration changes are only useful after the process reloads them.

Final notes

MCP works best when you connect tools that have a clear job. For Codex CLI, that often means search for current context, image or video tools for developer-facing artifacts, and utility tools such as short links for publishing workflows.

The complete Ace Data Cloud Codex MCP reference is here: https://platform.acedata.cloud/documents/codex-mcp-all

A Practical Guide to Using OpenCode IDE Extension with a Custom Provider

Germey — Tue, 08 Sep 2026 01:06:52 +0000

A coding assistant inside your editor is only useful if it can use the same model setup you already trust in the terminal.

OpenCode is interesting because the IDE Extension does not need to be treated as a completely separate integration. According to the Ace Data Cloud OpenCode IDE guide, the extension connects to the local OpenCode runtime and reuses the same Provider configuration used by the CLI. That makes it a practical path if you want one model configuration to work across Terminal, TUI, and editor workflows.

This guide walks through the setup pattern, the configuration file shape, and the minimal validation I would run before relying on it for real code edits.

What you can do

The OpenCode IDE Extension supports editors such as VS Code, Cursor, Windsurf, and VSCodium. The important boundary is that the extension reuses the OpenCode local runtime and Provider configuration; it does not mean the host editor itself has native Ace Data Cloud support.

That distinction matters. A terminal chat request proving your Provider works is not the same thing as proving the IDE can read files, propose edits, or invoke tools correctly. Treat the first setup as a small integration test, not just a login check.

How it works

The Provider configuration lives in opencode.json or opencode.jsonc. The documented setup uses the OpenAI-compatible AI SDK provider package and points it at the Ace Data Cloud API base URL.

Here is the core configuration shape from the guide:

{
  "provider": {
    "acedatacloud": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.acedata.cloud/v1",
        "apiKey": "{env:ACEDATACLOUD_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID" }
      }
    }
  },
  "model": "acedatacloud/MODEL_ID"
}

The fields worth double-checking are:

provider.acedatacloud: the custom provider namespace used by OpenCode.
npm: set to @ai-sdk/openai-compatible.
options.baseURL: set to https://api.acedata.cloud/v1.
options.apiKey: read from {env:ACEDATACLOUD_API_KEY} instead of hardcoding a token.
models.MODEL_ID: define the model ID you want to use.
model: select it through the namespaced value acedatacloud/MODEL_ID.

In practice, I would commit the opencode.jsonc structure if it is part of a shared dev environment, but keep the actual API token only in the developer or CI environment.

Step 1: configure the Provider first

Start with the Provider before thinking about the editor. Create or update opencode.jsonc, choose a real MODEL_ID from the model catalog you plan to use, and export the token as an environment variable:

export ACEDATACLOUD_API_KEY="your-token-here"

Then run OpenCode from the terminal and perform a tiny smoke test. I like using a boring prompt because it makes failures obvious:

Reply only OK

If the CLI cannot answer that, do not move on to the IDE Extension yet. Fix the Provider config first: base URL, environment variable name, and model ID are the likely places to check.

Step 2: install the IDE Extension

Once the Provider works in the terminal, install the IDE Extension. The guide gives two paths:

Run opencode in the integrated terminal of the editor and follow the official process to install the Extension automatically.
Or install it manually from the corresponding Marketplace.

After installation, reload the editor. That reload step is easy to skip, but it is often the difference between testing the current extension process and testing stale state from before the install.

Step 3: run minimal validation inside the editor

Now run the same simple check from the OpenCode Extension:

Reply only OK

This confirms that the extension can reach the local OpenCode runtime and that the runtime is using the configured Provider and model.

But I would not stop there. The document explicitly warns that successful ordinary chat cannot replace validation for file reading, editing, and tool invocation. A minimal validation set could be:

Ask the extension to summarize the currently open file.
Ask it to propose a small edit without applying it.
Ask it to apply a tiny, reversible change in a test file.
If your workflow uses tools, run one tool-based request and record the result.

Keep these tests intentionally small. The goal is not to benchmark intelligence; it is to verify the request chain between the editor, OpenCode runtime, Provider, and selected model.

Current boundaries to keep in mind

There are three boundaries I would document for a team rollout.

First, the Provider capability comes from the OpenCode runtime. The host editor is connecting to that runtime; it is not independently implementing Ace Data Cloud support.

Second, VS Code and forks such as Cursor, Windsurf, and VSCodium may differ by extension version and request behavior. Record the editor name and extension version when you validate the setup.

Third, validate the actual workflows you expect developers to use. Chat, file reading, edits, and tool invocation are different integration surfaces. Passing one does not automatically prove the others.

A rollout checklist

For a single developer, the setup is just a few steps. For a team, I would make it repeatable:

Add an example opencode.jsonc with ACEDATACLOUD_API_KEY as an environment reference.
Decide and document the MODEL_ID value.
Keep the token out of source control.
Install or update the IDE Extension.
Reload the editor.
Run Reply only OK from the extension.
Validate file reading and a safe edit in a test file.
Record editor name, editor version, extension version, and model ID.

That gives you a boring but reliable integration path: one Provider configuration, reused by the OpenCode runtime, then exercised through the IDE where developers actually work.

For the full configuration notes and current boundaries, see the source guide: OpenCode IDE Extension Setup Guide.

A Practical Guide to the OpenAI Responses API with Python

Germey — Mon, 07 Sep 2026 01:05:16 +0000

If you are building an AI feature today, the hard part is rarely “send one prompt and print one answer”; it is handling messages, streaming, usage data, and multi-turn context cleanly.

This guide walks through the OpenAI Responses API as exposed through Ace Data Cloud, using only the fields and examples from the public integration document. The goal is simple: make a minimal Python call, understand the response shape, then turn on streaming and multi-turn input without changing the mental model.

What you can do

The Responses API creates model responses from text or image input. The document describes a unified endpoint:

POST https://api.acedata.cloud/openai/responses

Requests use JSON and bearer-token authentication:

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

At minimum, the request needs:

authorization: selected in the platform UI or passed as a bearer token in code
model: for example, gpt-4.1
input: an array of messages, where each message has role and content

The documented message roles are user, assistant, and system. Common optional parameters include max_tokens, temperature, n, response_format, tools, and background. For real applications, the most immediately useful optional field is often stream, because it lets a UI render output progressively instead of waiting for the full response.

How it works

Think of the API as a response object factory. You send a model plus structured input, and it returns a response object with fields such as:

id: the generated response task ID
status: for example, completed or in_progress
model: the model used for the response
output: the assistant message content
usage: token statistics for the request and response

A completed response in the document includes an output array. Inside it, a message item contains content, and the text itself appears under content[].text with type output_text.

That structure is useful because your application does not have to scrape plain text. You can store the full response object for debugging, read usage.total_tokens for observability, and extract only the assistant text for display.

Make the smallest Python call

Here is the basic Python shape from the documentation, adapted to use a placeholder token:

import requests

url = "https://api.acedata.cloud/openai/responses"

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

payload = {
    "model": "gpt-4.1",
    "input": [
        {"role": "user", "content": "Hello"}
    ]
}

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

The important thing is the shape of input. Even for one user message, it is still an array. That makes the jump to multi-turn conversation straightforward later.

A typical completed response includes fields like this:

{
  "object": "response",
  "status": "completed",
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?"
        }
      ],
      "role": "assistant"
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 10,
    "total_tokens": 18
  }
}

For a production app, I would avoid assuming output[0] is always present. Check status, check error, then look for message items and output_text content.

Add streaming for web interfaces

For a chat UI, streaming makes the experience feel much better. The document enables this by adding stream: True to the payload:

import requests

url = "https://api.acedata.cloud/openai/responses"

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

payload = {
    "model": "gpt-4.1",
    "input": [{"role": "user", "content": "Hello"}],
    "stream": True
}

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

The streaming response returns data: lines. The document shows event types such as response.created, response.in_progress, response.output_item.added, response.output_text.delta, response.output_text.done, and response.completed.

The key event for rendering incremental text is:

{
  "type": "response.output_text.delta",
  "delta": "Hello"
}

The end condition is also explicit: when the event type is response.completed, the stream has finished. That gives you a clean loop for frontend or backend streaming handlers:

Read each data: line.
Parse the JSON payload.
Append delta values from response.output_text.delta.
Stop when type becomes response.completed.

Keep multi-turn context explicit

Multi-turn dialogue is handled by sending multiple messages in the same input array. The document’s example uses a previous user message, an assistant reply, and then a follow-up user question:

payload = {
    "model": "gpt-4.1",
    "input": [
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hello! How can I help you today? 😊"},
        {"role": "user", "content": "What did I just say?"}
    ]
}

This is simple, but it is also a good architectural constraint. Your application owns the conversation state. You decide which previous messages to include, how much history to keep, and whether to summarize older turns before sending them again.

Practical implementation notes

A few details are worth making explicit before wiring this into an app:

Keep the bearer token on the server side. Do not expose it in browser JavaScript.
Log id, status, model, and usage for debugging and cost visibility.
Use temperature only when you actually want more variation; the documented range is 0-2.
Use max_tokens when you need predictable response length.
Treat streaming as a transport concern. The request shape stays almost the same; only stream changes.

The nice thing about this API shape is that it scales from a “Hello” script to a real chat interface without introducing a second abstraction. You start with model and input, then add stream, multi-turn messages, or optional fields as the product needs them.

Full reference: OpenAI Responses API Integration Guide.

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

DEV Community: Germey

A Practical Guide to Adding MCP Servers to Codex CLI

What you can do

How it works

Keep the first configuration small

Add creative tools only when the repo needs them

A fuller config example

Final notes

A Practical Guide to Using OpenCode IDE Extension with a Custom Provider

What you can do

How it works

Step 1: configure the Provider first

Step 2: install the IDE Extension

Step 3: run minimal validation inside the editor

Current boundaries to keep in mind

A rollout checklist

A Practical Guide to the OpenAI Responses API with Python

What you can do

How it works

Make the smallest Python call

Add streaming for web interfaces

Keep multi-turn context explicit

Practical implementation notes

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

Generate an image with `images.generate`

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