DEV Community: Germey

How to Build a Simple Image Editing Workflow with an HTTP API

Germey — Wed, 21 Oct 2026 01:06:12 +0000

When an image workflow starts in a design tool, the hard part is often not the edit itself. It is making the edit repeatable: accepting a prompt, preserving the input references, authenticating the request, and keeping enough task information to troubleshoot a failed run.

This guide shows a small, practical workflow for editing one or more publicly accessible images over HTTP. The example uses the Nano Banana Images API, but the useful pattern is broader: send an explicit action, keep the input URLs and prompt together, and retain the task identifiers returned by the service.

What you can do

The API exposes one endpoint for image generation and editing:

Base URL: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Authentication: authorization: Bearer {token}
Content type: application/json

For editing, set action to edit, provide at least one item in image_urls, and describe the desired change in prompt. The URLs must be publicly accessible direct links. You can pass more than one image when the edit needs multiple reference materials.

The request can also include model, count, aspect_ratio, resolution, and an optional callback_url. The documented model options include nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-2.1, and nano-banana-pro.

How the request works

A useful mental model is that the request has three parts:

Action — tells the endpoint whether this is a generate or edit operation.
Materials — image_urls[] contains the source images for an edit.
Instruction — prompt describes what should change.

The response includes success, a task_id, a trace_id, and a data array. Each successful item in data contains the prompt and an image_url. Keep both identifiers in your application logs. They give you a way to associate a result with the original request when a workflow has several edits in flight.

Make your first edit with cURL

Start with a single reference image and a deliberately narrow instruction. A small edit is easier to evaluate than a prompt that asks for several unrelated changes at once.

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "model": "nano-banana-pro",
    "prompt": "Replace the background with a clean, softly lit studio backdrop while keeping the subject and its proportions unchanged.",
    "image_urls": [
      "https://example.com/input.png"
    ],
    "count": 1
  }'

Replace {token} and the example image URL with values you control. The API documentation accepts HTTP or HTTPS image URLs, although HTTPS is the safer default for production systems.

A successful response has this general shape:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Replace the background with a clean, softly lit studio backdrop while keeping the subject and its proportions unchanged.",
      "image_url": "https://cdn.acedata.cloud/assets/example.png"
    }
  ]
}

Treat the returned image_url as the artifact your next workflow step consumes. Do not assume that a request with multiple images produces one result: the API describes each requested image as an independent generation call, and data contains only successful results.

Use multiple references without losing context

Multiple references are useful when the edit combines materials—for example, a subject image and a separate visual reference. Put them in the intended order in image_urls and make their roles explicit in the prompt:

{
  "action": "edit",
  "prompt": "Keep the person from the first image, and use the second image only as the clothing reference.",
  "image_urls": [
    "https://example.com/person.png",
    "https://example.com/clothing.png"
  ],
  "count": 1
}

The important engineering detail is not the wording of the example. It is that the materials and instruction travel together as one request. That makes a job reproducible and gives you a clean record to store alongside the result.

Make longer jobs observable

For a synchronous prototype, waiting for the HTTP response can be enough. For a production workflow, the documentation recommends an optional callback_url. The endpoint can return a task_id immediately, then send the completed JSON to your publicly accessible webhook with a POST request.

A minimal webhook handler should:

validate that the payload contains the expected task_id;
store trace_id, success, and the returned data items;
record failures separately from provider safety rejections;
make processing idempotent, because retries should not create duplicate downstream work.

The documented error codes also give you a useful starting point for retry policy: 401 invalid_token is an authentication problem, 429 too_many_requests is a rate-limit signal, and 500 api_error indicates a server-side exception. A 403 forbidden response means the provider's safety policy rejected the call or result, so it should not be handled as a normal transient error.

A practical checklist

Before wiring this into an application, check the basics:

Keep the API token in server-side configuration, not in browser code.
Verify every image_urls value is a direct, publicly accessible link.
Start with count: 1 while validating prompts and output handling.
Persist task_id and trace_id with your request record.
Add callback_url when a long-running request should not hold an open connection.
Handle invalid_token, too_many_requests, api_error, and forbidden differently.

The result is a small but dependable image-editing building block: a prompt-driven operation with explicit inputs, observable execution, and a URL that can move into the next step of a pipeline. For the complete parameter reference and response details, see the Nano Banana Images API documentation.

How to Connect Seedance MCP to OpenCode for Terminal-Based Video Workflows

Germey — Tue, 20 Oct 2026 01:07:01 +0000

When a video task starts in a terminal, the awkward part is often context switching: leave the editor, open a separate tool, upload an image, copy the result back, and repeat. This guide shows how to connect a remote Seedance MCP server to OpenCode so a terminal session can request short videos through natural-language instructions.

What you can do

The integration exposes two documented tools:

seedance_generate_video for text-to-video generation
seedance_generate_video_from_image for image-to-video generation

That covers vertical short clips, product-demo animations, technical opening clips, and other cases where the first draft starts as either a description or an existing image. OpenCode connects to the remote MCP endpoint below; no local MCP server is required.

https://seedance.mcp.acedata.cloud/mcp

Authentication uses a Bearer token in the Authorization header. Keep the real token outside the configuration file and let OpenCode resolve it from an exported environment variable.

How the configuration works

OpenCode reads MCP definitions from opencode.json. Use ~/.config/opencode/opencode.json for a global setup, or opencode.json in a project root for a project-specific setup. The project-level file overrides the global one, so it is a useful place to test the integration first.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "seedance": {
      "type": "remote",
      "url": "https://seedance.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}"
      }
    }
  }
}

type declares a remote MCP connection, url selects the Seedance server, and enabled controls whether OpenCode loads it. The oauth field must explicitly be false: this server expects Bearer authentication, not an OAuth challenge. The headers.Authorization value supplies the token without putting the secret in JSON.

Store the token safely

Export the token before starting OpenCode:

export ACEDATACLOUD_API_KEY="replace with your real token"

Do not commit the real value to Git. If you keep it in a .env file, exporting matters. One documented way to load exported variables into the OpenCode process is:

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

Otherwise the placeholder may resolve to an empty value. The configuration can look correct while the request still carries an incomplete header.

Verify the MCP handshake

Start with:

opencode mcp list
opencode mcp debug seedance

A successful setup should show the Seedance connection as connected. If you see HTTP 401 or an SSE non-200 error, check these items in order:

ACEDATACLOUD_API_KEY is exported in the shell that launches OpenCode.
The header starts with the exact Bearer prefix.
oauth is present and set to false.

This separates an environment-variable problem from an authentication-mode problem and avoids putting a real secret into debug output.

Try a text-to-video request

After the handshake succeeds, stay in the OpenCode session and describe the output. For example:

Generate a vertical short video: a girl turns under a cherry blossom tree, slow motion, beautiful light and shadow

Specify orientation, subject, movement, and lighting rather than asking for a vague “cool video.” OpenCode can then use seedance_generate_video through MCP while remaining the interface for the request.

A developer-focused smoke test is:

Generate a 3-second video intro: a glowing code symbol </> transitions from blurry to clear, with particle effects in the background, in a tech blue tone

Short prompts are easier to debug before adding references or several creative constraints.

Try image-to-video

When you already have a still image, use the image-to-video capability instead of describing every visual detail again:

Use this image as a cover, generate a video with the camera slowly zooming in

The relevant tool is seedance_generate_video_from_image. This is useful for turning a product screenshot, illustration, or existing cover into a motion asset while preserving the starting composition.

A practical troubleshooting checklist

If the server does not connect, avoid changing several variables at once. Confirm the URL is exactly https://seedance.mcp.acedata.cloud/mcp, verify that the token is available to the OpenCode process, and run opencode mcp debug seedance again. If the connection is healthy but a generation request is not selected, use a model that supports native tool calls, since the available model and tool schema can change over time.

The complete configuration and current tool-list request are in the OpenCode + Seedance MCP guide. The practical takeaway is simple: keep credentials in the environment, keep oauth: false explicit, verify the handshake first, and only then build more elaborate terminal workflows.

How to Configure Kimi Code CLI with an OpenAI-Compatible Provider

Germey — Sun, 18 Oct 2026 01:07:10 +0000

If you like coding from the terminal, the frustrating part of trying a new AI coding CLI is usually not the CLI itself. It is the provider setup: where the config file lives, which base URL to use, which model name should go where, and how to verify that the key actually works.

This guide walks through configuring Kimi Code CLI to use Ace Data Cloud as an OpenAI-compatible provider. The goal is practical: install the CLI, add one provider block, verify the setup, and know what to check when it fails.

What you can do

Kimi Code is a terminal coding assistant. The Ace Data Cloud setup guide shows how to point it at an OpenAI-compatible endpoint by editing ~/.kimi/config.toml.

The important fields are:

Field	Value or role
`default_model`	`acedatacloud/MODEL_ID`
provider name	`acedatacloud`
provider `type`	`openai`
`base_url`	`https://api.acedata.cloud/v1`
`api_key`	your Ace Data Cloud API Key
model table	`[models."acedatacloud/MODEL_ID"]`
model parameter	`model = "MODEL_ID"`

The subtle part is MODEL_ID: the guide says to use the model name used by the API model parameter, not a service UUID or API UUID. It also recommends using the id value from the /v1/models response for precise validation.

How it works

Kimi Code reads its provider configuration from ~/.kimi/config.toml. By setting the provider type to openai, you tell Kimi Code to speak the OpenAI Chat Completions protocol to the configured base_url.

In this setup, Kimi Code sends model requests to:

https://api.acedata.cloud/v1

Ace Data Cloud handles the provider side, while Kimi Code keeps the local developer experience: run commands in a project, ask for changes, and iterate from the terminal.

You will need an API Key first. The documented path is to open the Ace Data Cloud application list, enter an available application, and copy the API Key.

Install Kimi Code

The guide gives three install options. On macOS or Linux, use the shell installer:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

On Windows PowerShell, use:

irm https://code.kimi.com/kimi-code/install.ps1 | iex

If you prefer npm, install the package globally:

npm install -g @moonshot-ai/kimi-code

After installing, the rest of the work is configuration rather than code.

Configure the provider

Open ~/.kimi/config.toml and add the Ace Data Cloud provider configuration:

default_model = "acedatacloud/MODEL_ID"

[providers.acedatacloud]
type = "openai"
base_url = "https://api.acedata.cloud/v1"
api_key = "your API Key"

[models."acedatacloud/MODEL_ID"]
provider = "acedatacloud"
model = "MODEL_ID"

Replace every MODEL_ID with the same model name. The source guide gives examples such as claude-opus-5 and gpt-6-sol, but the safest approach is to check the model catalog or validate against the /v1/models response and use the returned id.

A good final config should be internally consistent:

default_model should point to acedatacloud/<your model id>
the model table name should match that same acedatacloud/<your model id> string
the model field inside the table should be the raw model id
the provider should remain acedatacloud
type should remain openai

For example, if you choose gpt-6-sol, the structure would follow this shape:

default_model = "acedatacloud/gpt-6-sol"

[providers.acedatacloud]
type = "openai"
base_url = "https://api.acedata.cloud/v1"
api_key = "your API Key"

[models."acedatacloud/gpt-6-sol"]
provider = "acedatacloud"
model = "gpt-6-sol"

Do not mix model identifiers. A surprisingly common mistake is changing default_model but leaving the model table or model field on an older value.

Lock down the config file

Because ~/.kimi/config.toml contains the API Key, protect it on macOS or Linux:

chmod 600 ~/.kimi/config.toml

This does not replace secret management for teams, but it is a sensible local baseline. Avoid committing this file into a repository, and be careful when sharing terminal recordings or config snippets.

Verify the setup

The guide suggests three verification commands:

kimi doctor
kimi provider list
kimi -p "Reply only OK"

I would run them in that order. kimi doctor is the first sanity check. kimi provider list confirms that the provider is visible to Kimi Code. The final command is a minimal model call that should return only OK if the path is working.

If you get a 401, check the API Key. If Kimi Code reports that the model was not found, inspect the three model locations again: default_model, the [models."..."] table name, and the model field. They need to line up with the same API model id.

Start from a project directory

Once verification passes, enter a project and run:

kimi

That is the point where the setup becomes useful. You can ask the CLI to inspect files, propose changes, or help with debugging without leaving the terminal. The provider configuration stays in Kimi Code, while your project workflow stays local.

Wrap-up

This is a small integration, but it removes a lot of provider friction: one OpenAI-compatible base_url, one type = "openai" provider block, one model mapping, and three verification commands. If you are evaluating terminal coding agents, this is the kind of setup worth keeping reproducible.

For the original reference, see the Ace Data Cloud Kimi Code CLI setup guide: https://platform.acedata.cloud/documents/kimi-code-integration

Test blank, zero and service overrides in a branded AI workspace

Germey — Sat, 17 Oct 2026 02:13:55 +0000

A pricing form can save successfully while the customer journey still behaves differently from what the operator intended. One easy distinction to lose is a blank service markup versus an explicit zero: they represent different configuration states.

This guide is from the Ace Data Cloud team and uses the documented behavior of a white-label Studio. It provides a manual acceptance workflow for the selected site and service. Check the current configuration guide and actual checkout before applying it to a commercial offer.

Start with four separate cases

In the site's Price settings, the site-wide markup is the default. A service-specific markup takes priority when it is explicitly set.

Service configuration	Expected markup behavior	What the check must distinguish
No service override	Inherit the site-wide markup	The site default is the applicable setting
An override exists, but its markup field is blank	Inherit the site-wide markup	A blank field is not an explicit zero
Service markup is `0`	Apply no markup for that service	No markup does not make the underlying service free
Service markup contains an explicit percentage	Use the service percentage	Do not apply it on top of the site-wide percentage

Record the configuration state as well as the visible number. If the site-wide markup is also zero, two different states may produce the same price. That observation alone cannot show whether the service is inheriting the default or using an explicit override.

If you need a more distinguishing configuration, use an authorized test site and record its starting settings. Change one relevant setting at a time. Avoid changing a live commercial offer just to make a test easier to observe.

Compare the same customer path

Choose one service and a specific option within it. Enter through the site address customers will actually use, with an appropriate test account. Check the selected option, charging unit, displayed currency and price before moving to the checkout for that same purchase path.

Record the checkout amount and settlement currency separately. A number on a tool page and a number on a checkout page are not comparable until the service, option, quantity, charging unit and currency are aligned. Current offers or discounts can also affect the applicable price.

Keep two results separate:

Configuration check: Which setting should apply, and was that state saved?
Customer-path check: What price and conditions did the intended customer actually see?

A screenshot of an administrator's form answers only part of the first question. It does not establish checkout behavior, a completed payment, actual usage or an operator reward.

Treat removing an override as another operation

Removing a service override restores its default display settings and makes its markup inherit the site-wide setting. That can affect more than price: an override can also hold the service's custom name, description, ordering or visibility.

Record those values before changing the override. If the task is to clear just the markup field, do not substitute deletion of the whole override. After a deliberate removal, recheck the service's presentation as well as the price.

Keep display controls separate from spending controls

Hiding the top-up entry does not clear an existing balance or stop a customer from buying shared packages through another entry point. Likewise, hiding a tool is a display choice, not proof that API access has been revoked.

Studio branding uses a shared account, balance and package system. A course budget written in a handoff note is an operating agreement unless a real spending limit has also been configured and verified. Describe only the controls you have actually checked.

Copy a compact acceptance record

Use pass, fail or not checked for each result. Keep the record in an authorized location and share only the parts appropriate to the recipient.

Test time and time zone:
Site and intended customer entry:
Test account role or non-secret reference:
Service, selected option and quantity:
Site-wide markup:
Service state: absent / blank / zero / explicit percentage
Expected applicable markup and its basis:
Displayed price, charging unit and currency:
Checkout amount and settlement currency, if checked:
Saved configuration result and customer-path result:
Actual usage or order evidence, if a paid test was necessary:
Open issue, next check and owner:

Inspect the page and purchase path before deciding whether a paid generation is necessary. If it is, confirm the current service price and agree a small test scope first. Record the actual result and usage; do not generate repeatedly just to improve a screenshot. If a submission's outcome is unknown, reconcile the original task before deciding whether another request is needed.

Route a failed check to the right evidence

When a check fails, keep the observed result and choose the next investigation from that evidence. Use this table after the acceptance record; it is a navigation aid, not an automatic diagnosis.

What you observed	What to keep and check next
A saved setting looks right, but the customer price differs	Keep the site address, saved state and customer observation time. Recheck the same service, option, quantity, charging unit, currency and applicable offer using the record above.
A hidden catalogue entry can still be called through an API	Treat display visibility and credential access as separate checks. Use the credential permission matrix to record one intended allowed operation and one intended denied operation with an authorized test credential.
A paid test timed out or produced an unclear result	Preserve the original task reference and submission time. Use the sanitized support record to separate submission, task state and output acceptance before deciding on another request.

The two API guides apply when an API credential or request is actually involved. For a browser-only Studio issue, keep the tool-page evidence and use the current support route; do not introduce an API test just to follow a link.

Record what remains not checked and who will check it next. These checks do not themselves authorize a new payment, change a customer's price or grant API access.

Watch the three markup choices

This 45-second silent recap covers inheritance, explicit zero and a service-specific percentage:

Open the recap on YouTube.

For the current forms and rules, use the Studio capability and pricing guide.

Customer attribution, valid orders and distributable rewards need their own evidence. A successful task does not prove that a reward is payable; refunds and other applicable adjustments can change the records. Consult the customer attribution and earnings guide when checking those outcomes.

How to Connect Coze to an OpenAI Responses API Provider

Germey — Fri, 16 Oct 2026 01:04:25 +0000

If you want a private, browser-based AI workspace without rebuilding chat, user management, and model selection from scratch, Open WebUI plus an OpenAI-compatible endpoint is a practical place to start.

This guide walks through a small but production-minded setup: run Open WebUI in Docker, point it at Ace Data Cloud, verify the connection outside the UI, and avoid the configuration mistakes that tend to waste the most time.

What you are building

The architecture is deliberately simple. Open WebUI provides the browser interface, local conversation storage, user roles, and optional knowledge-base features. Ace Data Cloud sits behind it as an OpenAI-compatible model endpoint.

The important connection values are:

Base URL: https://api.acedata.cloud/v1
Chat endpoint: POST https://api.acedata.cloud/v1/chat/completions
Authentication header: Authorization: Bearer {token}
Model discovery: GET https://api.acedata.cloud/v1/models

That final endpoint matters more than it may seem. Model catalogs change, so it is safer to let Open WebUI load the current list than to copy a model ID from an old setup note.

There is also a path detail worth understanding up front. The base URL must match the route family you intend to use. https://api.acedata.cloud/v1 correctly produces /v1/chat/completions. The alternative base https://api.acedata.cloud/openai is also available, but appending /v1 to that route creates https://api.acedata.cloud/openai/v1/chat/completions, which does not exist and returns 404.

Start Open WebUI with Docker

Create an API token in your Ace Data Cloud application, then run the container below. Keep the token out of shell history in a real deployment—for example, load it from an environment file or secret manager rather than committing it to a repository.

docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e WEBUI_SECRET_KEY=$(openssl rand -base64 32) \
  -e OPENAI_API_BASE_URL=https://api.acedata.cloud/v1 \
  -e OPENAI_API_KEY={token} \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

Each setting has a narrow job:

OPENAI_API_BASE_URL tells the client where the compatible API begins. Keep the trailing /v1 in this configuration.
OPENAI_API_KEY carries your Ace Data Cloud token.
WEBUI_SECRET_KEY protects web sessions; the command generates a fresh value.
-v open-webui:/app/backend/data persists conversations and user data across container restarts.

Open http://your-server-IP:3000 after the container starts. The first account registered becomes the administrator, so do the initial signup yourself rather than leaving a fresh instance exposed.

Inside Open WebUI, go to Admin Panel → Settings → Connections and use Verify Connection. Then open Settings → Models to filter or pin the models you actually want users to see. You can also add the same Base URL and API key directly through the Connections interface instead of environment variables; Open WebUI will call /models to populate the catalog.

Verify the API before debugging the UI

When a chat interface says only “connection failed,” it hides too many possible causes: a malformed base URL, an invalid token, an unavailable model, or a network problem. A direct request separates the API layer from the UI layer.

First retrieve the current model list, choose an ID returned there, and replace MODEL_ID below:

curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

A successful request returns an OpenAI-compatible chat.completion object. If you receive HTTP 403 used_up, the token is valid but its balance is insufficient. If you receive a 404, inspect the URL first—especially the common accidental /openai/v1 combination.

This is the debugging order I prefer as a builder: prove the token and route with curl, verify the connection in the admin panel, and only then investigate model or browser behavior. It avoids changing several layers at once.

Make the setup safer for a small team

Open WebUI supports multiple users, but a public registration screen can also turn into unplanned API usage. In Admin Panel → Users, set the default user role to pending so each new account requires review. Available roles include Pending, User, and Admin.

For document chat, Open WebUI uses ChromaDB for vector storage by default. The documented embedding option is text-embedding-3-large. Original documents remain on your server, while matched segments are sent to the model during retrieval. If uploaded documents do not produce chat results, check the embedding model in the RAG settings before assuming the chat endpoint is broken.

If you place nginx in front of the container, add:

proxy_buffering off;
client_max_body_size 100M;

The first setting avoids buffered streaming behavior, while the second allows larger uploads. And do not skip the Docker volume: without /app/backend/data persistence, a container replacement can take conversations and local user state with it.

A short troubleshooting checklist

Before changing the deployment, check these in order:

Is the base URL exactly https://api.acedata.cloud/v1?
Does a direct request to /v1/chat/completions work with the same token?
Is the selected model present in the current /v1/models response?
Is the persistent volume mounted?
For RAG, is text-embedding-3-large selected as the embedding model?
For team access, are new users held in the pending role?

The useful part of an OpenAI-compatible interface is not that every client becomes identical; it is that you can test one clean HTTP boundary and then choose the interface that fits your team. Keep that boundary observable, start with the smallest deployment, and use the full Ace Data Cloud Open WebUI setup reference when you need to revisit the exact connection rules.

A Practical Guide to Building Multi-Track Music Workflows with the Suno Projects API

Germey — Thu, 15 Oct 2026 01:05:12 +0000

If you have ever tried to turn a single generated audio clip into an editable arrangement, you have probably hit the same wall: one file is easy to play, but hard to iterate on.

The Suno Studio Projects API gives you a project-level workflow for that next step: create a project, add source material, render a reference mix, generate new track candidates, and commit the one that fits.

What you can do

The core endpoint is:

POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: <a new UUID for each write operation>

The API is action-based. Every request sends an action field, and the same endpoint handles project operations such as:

create — create an empty project
retrieve — read the latest project state
save — save the complete project state
upload — create an asset from an HTTPS audio URL
add_track — place completed audio into the project
render — export the current audible mix and get a reference audio_id
generate_track — generate new track candidates
replace_section — generate candidates for a partial replacement
commit_candidate — commit a selected candidate into the project
remove_track — remove a track

Most write operations require an Idempotency-Key header. The exception is retrieve. That matters in real integrations: if a paid generation times out or the client disconnects, you should query the original task or reuse the same idempotency key instead of blindly submitting a different request.

How the workflow fits together

A project workflow is mostly about passing the right IDs forward.

The create response gives you data.id, which becomes the project id for later calls. After the first save or any modifying operation, you also get a version_id. Use the latest version_id when modifying, generating candidates, or exporting.

When you upload audio, the completed task returns response.data.candidate.audio_id. That is the ID you use with add_track; do not pass the original audio URL into add_track.

For new generated parts, there are two more IDs to track:

render_audio_id comes from the final render task response as response.data.audio_id.
operation_id and candidate_id come from the final generation task and are used when committing a candidate.

One subtle but important detail: time can mean two different things. start_seconds and end_seconds refer to seconds inside the source audio. start_beats and end_beats refer to beats on the project timeline. The default state.timing.bps is 2, so a 41-second clip starting at beat 0 ends at beat 82 by default.

Step 1: create and save a project

Start with a small project object. A newly created project has no version_id, so the first save can omit it.

BASE_URL="https://api.acedata.cloud"

curl -X POST "$BASE_URL/suno/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "create",
    "title": "Demo arrangement"
  }'

The response includes a project id and an initial state, typically with empty tracks and timing.bps set to 2.

Then save the complete state:

{
  "action": "save",
  "id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
  "title": "Demo arrangement",
  "state": {
    "tracks": [],
    "timing": {
      "bps": 2
    }
  }
}

After this point, keep the returned version_id. Old versions can be rejected, so do not cache a project state and edit it much later without retrieving the latest copy first.

Step 2: upload audio and add it as a track

To bring source material into a project, upload from an HTTPS URL that is publicly accessible and that you have the right to use.

{
  "action": "upload",
  "id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
  "version_id": "8f0c62fb-304f-420e-9707-426e8b64b5e3",
  "audio_url": "<HTTPS_AUDIO_URL>",
  "async": true
}

Async operations return a task_id first. That only means the task was accepted. Poll the task endpoint until the task has finished_at and response.success is true:

POST /suno/tasks
Content-Type: application/json

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

When upload completes, take candidate.audio_id and add it to the project:

{
  "action": "add_track",
  "id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
  "version_id": "8f0c62fb-304f-420e-9707-426e8b64b5e3",
  "audio_id": "b21be571-bfe4-47c1-b59c-2abc55c6f9c3",
  "name": "Source demo",
  "start_beats": 0
}

Optional fields such as color, gain, start_beats, and end_beats let you control placement and volume. The default color is #7251F7, and gain defaults to 1.

Step 3: generate a new track candidate

For generate_track, first save an empty target track in the complete project state. At minimum, the target track needs an id, type: "audio", and clips: []. A fuller empty track can include takeLanes, mute, solo, amplitude, instrument, and color.

Next, render the current audible mix:

{
  "action": "render",
  "id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
  "version_id": "cb0a82c9-aa5b-48cc-9395-0528675fc18d",
  "title": "Demo source mix",
  "lyrics": "[Instrumental]",
  "async": true
}

When the render task succeeds, use its audio_id as render_audio_id in generate_track:

{
  "action": "generate_track",
  "id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
  "version_id": "cb0a82c9-aa5b-48cc-9395-0528675fc18d",
  "source_audio_id": "b21be571-bfe4-47c1-b59c-2abc55c6f9c3",
  "render_audio_id": "41038732-4dc4-40bf-b00d-2728d99bc26e",
  "model": "chirp-v5",
  "start_seconds": 12,
  "end_seconds": 20,
  "stem_control_tags": "add Piano",
  "batch_size": 2,
  "instrumental": true,
  "tags": "warm piano, cinematic"
}

Supported model names include chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild, and chirp-v6-mini. Availability for a specific combination is ultimately reflected in the final task state.

Step 4: commit the candidate you actually want

Generation does not modify the project immediately. It gives you candidates. After listening or inspecting results, use commit_candidate with the returned operation_id, selected candidate_id, and target track_id.

That separation is useful: your app can present several takes to a user, let them choose one, and only then update the project version.

In practice, I would wrap this workflow in a small state machine:

Store project_id and latest version_id.
Store every async task_id before polling.
On timeout, retrieve the task instead of resubmitting.
After any successful modifying operation, replace the stored version_id.
Before editing state, retrieve the full project and preserve unknown fields.

That last point prevents accidental data loss. save expects the complete project state, not a partial patch.

Closing thoughts

The useful mental model is: treat /suno/projects less like a single generation endpoint and more like an arrangement workspace. You create durable project state, attach source material, ask for candidates, and commit only the result that belongs in the mix.

If you are building a tool where users iterate on stems, intros, backing tracks, or replacements, this project-based flow is much easier to reason about than repeatedly juggling standalone audio files.

Full reference: https://platform.acedata.cloud/documents/suno-projects-integration

Check DNS and TLS before sending an API key to a new hostname

Germey — Wed, 14 Oct 2026 18:24:00 +0000

Before a customer's first API request, verify the hostname separately from the service operation. A branded portal's website domain and API domain can have different jobs. A working homepage establishes only part of the path.

This guide uses a small Python probe to check DNS resolution and a verified TLS connection before sending any API credential. It sends no HTTP request and has no input for an API key.

Disclosure: this is a practical guide from the Ace Data Cloud team. The setup notes reference our current public documentation; the probe uses Python's standard library and can be applied to an HTTPS hostname you are authorized to check.

Start with the intended API hostname

Keep these two addresses separate in your acceptance record:

Address	Intended role
`portal.example.com`	The website where customers read documentation and manage their account
`api.example.com`	The hostname their program uses for documented API requests

These are reserved example names. Replace them with the actual addresses from your configuration.

For Ace Data Cloud, the page-domain and API-domain controls each provide their own CNAME target. Copy the target from the correct control in the current console. Do not copy an old screenshot or replace an existing DNS record without checking what currently uses it. DNS resolution and HTTPS activation are separate checks.

The current domain setup guide covers those controls. This article focuses on the next client-side check.

Watch the DNS and TLS preflight in 45 seconds

This silent video uses English on-screen text and English captions to walk through the checks below. It separates DNS, connection and TLS checks from the later HTTP route and credential-permission tests.

Watch the DNS and TLS checklist on YouTube.

Keep the actual failure stage and the client used for the check. A verified TLS connection does not prove that the expected application is there or that an API operation is authorized. The Python probe below sends no HTTP request and accepts no API key.

Probe DNS and TLS without a key

Save the following as api_hostname_preflight.py. It uses Python 3 and the runtime's normal trust store. The argument is a bare hostname: no scheme, port, path, query string or credentials.

import argparse
import json
import socket
import ssl
from datetime import datetime, timezone


def main():
    parser = argparse.ArgumentParser(description="Resolve a hostname and verify TLS; send no HTTP request")
    parser.add_argument("hostname", help="Bare hostname, without scheme, port, path or credentials")
    args = parser.parse_args()
    host = args.hostname.rstrip(".")
    if not host or any(c in host for c in "/:@?#") or any(c.isspace() for c in host):
        parser.error("Pass a hostname only, not a URL, port or credential")
    try:
        host = host.encode("idna").decode("ascii")
    except UnicodeError:
        parser.error("Hostname could not be converted to an ASCII DNS name")

    report = {"hostname": host, "port": 443,
              "started_at": datetime.now(timezone.utc).isoformat()}
    stage = "dns"
    try:
        answers = socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM)
        report["resolved_addresses"] = sorted({answer[4][0] for answer in answers})
        stage = "connect"
        context = ssl.create_default_context()
        with socket.create_connection((host, 443), timeout=5) as connection:
            stage = "tls"
            with context.wrap_socket(connection, server_hostname=host) as tls:
                certificate = tls.getpeercert()
                report.update(status="tls_verified", connected_peer=tls.getpeername()[0],
                              tls_version=tls.version(),
                              certificate_not_after=certificate.get("notAfter"))
    except ssl.SSLCertVerificationError as error:
        report.update(status="certificate_rejected", stage=stage,
                      verification_code=error.verify_code)
    except (OSError, ValueError) as error:
        report.update(status="probe_failed", stage=stage, error_type=type(error).__name__)
    report["checked_at"] = datetime.now(timezone.utc).isoformat()
    print(json.dumps(report, indent=2))
    return 0 if report["status"] == "tls_verified" else 1


if __name__ == "__main__":
    raise SystemExit(main())

Run it against the API hostname you intend to configure:

python3 api_hostname_preflight.py api.example.com

The code opens port 443, verifies the certificate using the configured trust store, and closes the connection. It does not send a request path, an Authorization header, a cookie or a generation request.

ssl.create_default_context() enables certificate verification. Passing server_hostname=host lets TLS use the hostname for SNI and hostname verification. Do not replace this with an unverified context to make a failing check appear successful.

The five-second timeout applies to connection and TLS socket operations. Operating-system DNS resolution has its own behavior, and trying multiple addresses can make the total run take longer than five seconds. This is a small diagnostic probe, not a full monitoring agent.

Read the result at the right level

The result is JSON, with UTC timestamps and a clear stage:

Result	What it tells you	What to check next
`tls_verified`	This client resolved the name and accepted a TLS connection for it using this runtime's trust configuration	The intended application route and later authenticated API behavior
`certificate_rejected`	Certificate verification failed	The hostname, certificate validity and chain, local clock and trust configuration
`probe_failed`, stage `dns`	The system resolver did not return usable address information	The configured name, DNS records and the client's resolver
`probe_failed`, stage `connect`	Address resolution completed, but connection setup or its prerequisites failed	Reachability, port 443, local network policy and client configuration
`probe_failed`, stage `tls`	A connection was made, but the TLS operation failed or timed out	TLS configuration and the network path; this is not an API-key response
Argument error, exit code 2	The input was not a supported hostname	Remove the scheme, port, path or credentials before probing

On success, resolved_addresses records the local resolver's answers, while connected_peer records the connection actually selected. The connection helper may resolve the name again, so those observations can differ. A successful connection checks one selected address; it does not certify every A or AAAA record.

This is also not an authoritative DNS lookup or a check of the entire CNAME chain. Resolvers, proxies and trust stores can change what a particular machine observes. Some networks synthesize addresses even for names that do not exist, which can move an eventual failure from the DNS stage to the connection or TLS stage. Preserve the observed stage instead of assigning an expected one. Compare the configured CNAME with the current setup instructions separately.

Keep routing and authorization as separate tests

A TLS pass establishes neither the right application route nor access to a service. A different application can present a valid certificate for the hostname. The probe intentionally makes no HTTP request, so it cannot identify that application.

After the API-domain status is ready, inspect the documented Base URL and request path. In Ace Data Cloud's Usage and Testing area, View Code helps you inspect the selected API example before running it. An example containing a real key should stay private. Manually maintained documentation needs its own address review; do not assume an old hard-coded host was rewritten automatically.

A later HTTP response is a new piece of evidence. For example, a route returning 404 or an authenticated request returning 401 should be investigated at that layer. Neither response proves that DNS is broken. Preserve the service's actual status and sanitized error rather than relabelling it.

A branded API hostname also does not create credential isolation. The credential-permission guide covers allowlists and allowed-versus-rejected operation tests separately.

Hand off a small, useful record

Keep the probe output with the intended hostname, the network it was run from, and the expected API configuration. Before sharing it, check whether hostnames or network addresses disclose information that belongs in a private support channel.

A concise handoff can look like this:

Intended API hostname:
Source of expected host / domain configuration:
Client and network used for the check:
Started and checked at (UTC):
DNS answers and connected peer, if appropriate to share:
TLS result and certificate expiry, or exact failed stage:
HTTP route check: not performed / observed result:
Authenticated operation: not performed / observed result:
Remaining uncertainty:

Do not attach a full environment dump or a credential-bearing command. Use the support-report guide to prepare any additional logs or screenshots.

Once these transport checks and the intended route are understood, select one documented, small API operation with an authorized test customer's own credential. Confirm its current cost, inspect the actual response and usage record, and preserve any original asynchronous task ID before considering a retry. That final operation is a separate acceptance step; the DNS/TLS probe has not performed it for you.

How to Poll Async Image Tasks with the Flux Tasks API

Germey — Wed, 14 Oct 2026 01:11:23 +0000

Async image generation needs two separate operations: creating the work and checking the task that was already created. Save the returned platform task ID so a slow response or a page refresh does not turn into an accidental second generation request.

This guide from Ace Data Cloud covers the Flux Tasks API for an existing image-generation task. The same task endpoint also supports platform task IDs returned by Flux video generation. The request and response examples below are illustrative; they are not results from a live call made for this article.

Updated October 18, 2026: restored the missing endpoint names, field names and code examples.

What you can query

Use the task ID returned by the original generation request:

Base URL: https://api.acedata.cloud
Endpoint: POST /flux/tasks
Authentication: authorization: Bearer {token}
Headers: accept: application/json and content-type: application/json
Single task action: retrieve, with an id
Batch action: retrieve_batch, with an ids array

These are retrieval operations even though the endpoint uses HTTP POST. Keep them separate from a generation request. Use an authorized token and an existing task ID; the placeholders in this article will not retrieve a real task.

Retrieve one task

Replace {token} and YOUR_EXISTING_TASK_ID in your own authorized environment. Avoid publishing command output that contains credentials, customer inputs or private result links.

curl --max-time 20 -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "id": "YOUR_EXISTING_TASK_ID",
    "action": "retrieve"
  }'

The following shortened example illustrates a completed task record. In the maintained reference, the original request is in request, and the generation result is nested in response:

{
  "id": "YOUR_EXISTING_TASK_ID",
  "created_at": 1736304669.779,
  "started_at": 1736304669.839,
  "finished_at": 1736304679.439,
  "elapsed": 9.6,
  "request": {
    "action": "generate",
    "size": "1024x1024",
    "prompt": "a white siamese cat"
  },
  "trace_id": "EXAMPLE_TRACE_ID",
  "response": {
    "success": true,
    "task_id": "YOUR_EXISTING_TASK_ID",
    "data": [
      {
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"
      }
    ]
  }
}

The reference documents these timing fields:

created_at: creation time, as a Unix timestamp in seconds.
started_at: execution start time, as a Unix timestamp in seconds.
finished_at: completion time; omitted when the task has not completed.
elapsed: execution duration in seconds; omitted when the task has not completed.

finished_at marks completion, not necessarily a successful usable image. Inspect the nested response and its success or error information. For this successful image example, the output location is response.data[].image_url. An HTTP 200 response from the lookup alone does not establish that generation succeeded.

Keep enough state to resume the lookup

A small application record can retain the platform task id, the relevant internal job reference, the last confirmed state, the query time and trace_id when available. Store task timing and the final response when returned, with access controls appropriate to its contents.

Keep a reference to the original input in an authorized store when it is needed for support. A task record can contain the original prompt and output links; copying its entire body into a public ticket is unnecessary.

Distinguish the task's last observed state from the state of the poller. For example, “last observed pending; lookup timed out” means the latest observation is unavailable. It does not establish that the task failed or was cancelled.

Retrieve a batch of existing tasks

For a dashboard or recovery worker, send multiple task IDs using retrieve_batch:

curl --max-time 20 -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "ids": ["YOUR_FIRST_EXISTING_TASK_ID", "YOUR_SECOND_EXISTING_TASK_ID"],
    "action": "retrieve_batch"
  }'

The batch response has an items array and a count. Each returned item follows the task-record structure used for a single lookup. Match items to your saved jobs by id; keep each job's state separate.

A backend worker can consolidate polling so every browser tab does not independently query the same task. Choose a polling interval, per-query timeout, total observation window and maximum query count appropriate to the application. Those are your monitoring limits, not a request to cancel the generation task.

Handle lookup errors separately from generation results

The reference lists these HTTP statuses and error codes:

HTTP status	Error code	Next check
400	`token_mismatched`	Check required parameters and the request shape
400	`api_not_implemented`	Check the supported path and action
401	`invalid_token`	Check the authorized token used for the lookup
429	`too_many_requests`	Slow down subsequent queries
500	`api_error`	Retain the diagnostic reference and investigate the query failure

An illustrative error body is:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "EXAMPLE_TRACE_ID"
}

Record whether an error came from the lookup request or from the stored generation response. A lookup error by itself does not determine the generation outcome. After a query timeout or rate limit, preserve the existing task ID and use a bounded retrieval policy. Do not automatically resubmit generation just because observation stopped.

A polling workflow to review

Persist the task ID returned by the original generation request.
Query /flux/tasks using action: "retrieve" and that same id.
If the returned record has no finished_at, retain the pending observation and query again within the monitoring limits.
When completion is recorded, inspect response for success or failure and retain the relevant result.
When a query fails or the observation window ends, record that condition separately and keep the original ID for reconciliation.

For batch processing, use retrieve_batch while keeping the same per-task checks. Consult the maintained Flux Tasks API integration guide for the complete request and response examples.

Test API credential permissions separately from your service catalog

Germey — Tue, 13 Oct 2026 12:40:50 +0000

A branded API portal has two separate questions to answer: which services should customers discover, and which operations should a particular credential be allowed to call?

Treat those as separate acceptance tests. A screenshot of a tidy service catalog cannot establish the permissions of an API key.

Disclosure: this guide uses Ace Data Cloud's current white-label catalog and credential documentation. It is written by the Ace Data Cloud team. The examples below are test designs, not reported customer results.

Watch the three permission cases

This 40-second visual guide compares catalogue visibility with credential scope. It is silent, with English on-screen text and English and Simplified Chinese subtitles available in the player settings.

Watch the permission checklist on YouTube.

The three fictional cases are:

A: visible in the catalogue and inside the intended credential scope.
B: visible in the catalogue and outside the intended credential scope.
C: hidden from the catalogue but still inside the intended credential scope.

These are test setups, not observed API results. Hold the other prerequisites valid and record the actual response; a hidden catalogue entry does not establish that access was revoked, and a generic error does not establish an allowlist denial.

Record the boundary each setting controls

In the current portal, service visibility and documentation visibility are configured separately. Hiding a service does not automatically hide its documentation. A saved detail link may still open even when its directory entry is hidden.

Credential restrictions require their own configuration and evidence:

Setting or check	What it establishes	What to verify separately
Service catalog visibility	Which service entries appear in the catalog	The credential's permitted API operations
Documentation visibility	Which documentation entries or subtrees appear	Whether an existing direct link is accessible
`allowed_api_ids`	The configured API allowlist for that credential	An allowed request and an appropriately designed rejected request
`expired_at`	The configured expiry time	Behavior after expiry, where safely testable
`limited_amount`	The configured credential usage limit	The documented unit, current usage and enforcement behavior

These settings do not create a separate customer database or billing system for each branded site. A customer's existing balance also does not disappear when a purchase button is hidden.

Check what an empty allowlist means

The current credential-creation documentation says that allowed_api_ids accepts API UUIDs and that an empty array is normalized to no restriction. It is therefore unsafe to use [] as shorthand for “deny every API.” The documented default also allows an unrestricted value.

A non-empty list should contain the actual API IDs you intend to allow. Obtain them through the documented API catalog for the relevant service. Do not substitute model names, route strings, display titles or an Application ID.

“No restriction” here describes this particular credential filter. It does not waive service acquisition requirements, available credits or the other conditions of a request.

If your application's policy requires every newly issued test credential to have an explicit allowlist, validate that policy before sending a creation request. This small offline guard rejects an empty or malformed list:

from uuid import UUID


def require_explicit_allowlist(api_ids):
    if not isinstance(api_ids, list) or not api_ids:
        raise ValueError("Provide a non-empty list of allowed API UUIDs")

    normalized = []
    for item in api_ids:
        if not isinstance(item, str):
            raise ValueError("Each API ID must be a UUID string")
        normalized.append(str(UUID(item)))

    return list(dict.fromkeys(normalized))

This function makes no network calls, creates no credential and does not inspect any key. It only validates the local input shape. A well-formed UUID can still name a nonexistent API, so the service must validate the IDs and enforce the resulting scope. The guard also does not protect requests made through another client; runtime authorization belongs on the server.

Run the guard locally

Paste the function above and this example into one Python file. The UUID is a synthetic parser fixture; the example does not establish whether a matching API exists.

synthetic_id = "00000000-0000-4000-8000-000000000001"
cases = [
    ("empty", []),
    ("malformed", ["not-a-uuid"]),
    ("duplicate", [synthetic_id, synthetic_id]),
]

for label, candidate in cases:
    try:
        checked = require_explicit_allowlist(candidate)
    except ValueError:
        print(f"{label}: rejected locally")
    else:
        print(f"{label}: {len(checked)} unique UUID(s)")

The output is:

empty: rejected locally
malformed: rejected locally
duplicate: 1 unique UUID(s)

The duplicate case confirms that the local guard retained one syntactically valid UUID. Server-side ID validation and permission checks remain separate steps. This example performs no network request and creates no credential.

Test one allowed operation and one excluded operation

Use an authorized test account and a dedicated test credential. Do not repurpose a customer's production key or assume that owning a branded site gives you permission to manage another account's credentials.

Before calling anything, record the intended API scope, expiry and usage limit. Confirm the current service documentation and the cost of any operation you plan to run. Use synthetic inputs or material you have permission to use.

Build a small matrix for the actual service:

Case	Setup	Evidence to capture
Included API	Valid credential, explicitly included API, otherwise valid request	Actual response and associated usage or request record
Excluded API	Same test identity; API deliberately excluded from its allowlist	Actual rejection and the documented interpretation of that response
Expired credential	Dedicated short-lived test credential after its configured expiry	Rejection after expiry, or an explicit “not exercised” result
Catalog-only change	Change a test site's display setting while holding credential policy constant	Catalog behavior and credential behavior recorded as separate observations

Keep unrelated inputs valid where the service permits it. If the excluded request also has malformed parameters, missing service access or an invalid key, its failure may not demonstrate that the API allowlist worked. Record the actual reason instead of labelling every error an authorization success.

Watch the invalid-key test case. This 49-second fictional example uses synthetic English narration, with English and Simplified Chinese subtitles selectable in the player. It shows why an invalid-key failure leaves allowlist enforcement unproven; no live API request is made.

Do not pre-fill the matrix with a universal error code. Read the service's documented response and preserve the observed status and sanitized message. Do not deliberately exhaust a budget just to prove a usage limit. Configuration review, a live test and an untested assumption are different evidence levels.

For an asynchronous operation, preserve the original task ID when one is returned. Check that task after a timeout before considering another paid submission.

Keep an acceptance record without keeping the secret

This template captures the useful evidence without asking for the credential value:

Site and service:
Test time and time zone:
Authorized test identity / role:
Credential label (not the secret):
Configured API IDs, expiry and usage limit:
Operation expected to be allowed:
Operation expected to be rejected:
Observed status and sanitized result for each case:
Non-secret request/task reference, if appropriate:
Evidence level: settings reviewed / live result / not exercised
Remaining uncertainty and next owner:
Test credential cleanup owner:

Remove authorization headers, cookies, full tokens, private inputs and access-bearing result URLs from shared evidence. Credential-management responses can themselves contain secrets, so avoid logging their complete bodies. Use the support-ticket redaction guide when preparing an attachment.

After testing, have the authorized owner retire credentials that are no longer needed, following the service's documented process. Verify the credential label and dependents before changing it. Keep the catalog result and the authorization result as separate conclusions in the handoff.

For this implementation, the catalog configuration guide describes the display controls, and the credential creation reference defines the accepted fields and their current semantics.

Create reproducible API support tickets without sharing credentials

Germey — Mon, 12 Oct 2026 18:22:21 +0000

When you operate a branded AI API portal, customers need a clear route from a failed request to useful help. A report such as “the API is broken” leaves the next person guessing. A complete terminal log can create a different problem: it may expose a working API key or private customer input.

A useful support ticket captures the failing step, enough context to investigate it, and the evidence that can be shared safely.

Disclosure: this is a practical guide from the Ace Data Cloud team. The sample below is fictional and contains no customer data.

Start with the step that failed

Separate the website journey from the API operation. A customer might be unable to open a custom domain, sign in, locate the right service documentation, submit an API request, check an asynchronous task, or download a finished result. These are different starting points for an investigation.

Write down the last step that worked and the first step that failed. For example: “I can open the portal and read the service guide. The documented request returns an error.” That narrows the problem before anyone changes DNS or account settings.

Use the service's public name and the request path from its current documentation. A branded website address does not establish the correct API base URL. Check the documented request destination separately.

Use a small, structured report

Here is a template a developer can paste into an approved support channel:

Site: <site address>
When: <date, time, and time zone>
Service or tool: <public service name>
Step: <submit request / check existing task / download result>
Request: <HTTP method and documented path, with sensitive parts removed>
Expected: <one sentence describing the intended result>
Observed: <HTTP status and sanitized error code/message>
Reference: <non-secret request or task ID, if the API provides one>
Repeatability: <happened once / intermittent / reproducible>
Last known success: <time, if known>
Recent relevant change: <one change, or none known>

A time zone matters when the customer and support team work in different regions. Keep the original error code and useful wording after removing sensitive material. Turning every failure into “server error” discards information that could explain the problem.

Some APIs return a request identifier in a header; others return a task identifier in the body. Use the identifier actually supplied by that service. If none was returned, say so. Check whether an identifier is safe to share before putting it in a public comment.

Review the whole attachment before sending it

Secrets can appear in several places, so removing one header is only part of the check:

Evidence	Review before sharing
Request headers	Remove credentials from `Authorization`, API-key headers, and cookies.
Request and redirect URLs	Check query parameters and path segments at every hop for tokens, signatures, private identifiers, or customer data.
Response headers	Review `Location` for signed redirect URLs and remove credentials from `Set-Cookie` and other sensitive headers.
Request body	Replace private prompts, documents, and media references with a minimal synthetic example when possible.
Response body	Check for echoed inputs, personal data, and result links that grant access to private files.
Screenshot or terminal output	Crop or remove credentials, account details, unrelated tabs, and sensitive URL parameters. Inspect the final exported file.

A signed download URL may grant access to a result even when it contains no field named api_key. Treat it according to the access it grants. If it is unnecessary for the investigation, omit it from the report.

As G pointed out in the comments, a clean initial request URL does not make the redirect chain safe to share. A 302 response can put a signed token in its Location header, and a verbose client may log both that header and the follow-up URL. Inspect every hop and the final exported log; removing Authorization from the first request is not enough. Keep the status and sanitized destination path when useful, while removing access-bearing parameters and private data.

Never ask a customer to paste their password, verification code, full API key, complete authorization header, or payment details into a support ticket. For an authorized reproduction, use an appropriate test account and its own credentials. If a live credential has already been exposed, follow the service's credential-revocation process and remove the exposed copy from the discussion where possible.

Watch why removing the query is not enough

This fictional relative URL shows where an access-bearing placeholder can remain. It is not a live endpoint; DEMO_TOKEN stands for a made-up access credential.

Before:        /result/DEMO_TOKEN?sig=DEMO
Query removed: /result/DEMO_TOKEN

Removing ?sig=DEMO still leaves the credential in the path. The second line is not ready to share in this example. Omit the access-bearing URL and record only fields approved for the support recipient, such as the failed stage, observed status and observation time. Keep any necessary reference in an authorized support system.

The 44.6-second walkthrough uses locally synthesized English narration, with English and Simplified Chinese captions. It illustrates one redaction mistake; it is not a general-purpose sanitizer.

Open the narrated URL example on YouTube.

Preserve the original task after a timeout

For an asynchronous operation, submission, completion, and downloading the result are separate stages. A browser or client timeout does not prove that the server rejected the work.

For an asynchronous ticket, keep the first submission time separate from the time you checked its status. Add these fields to the general report above:

First submitted at: <date, time, and time zone, or unknown>
Original task ID: <non-secret ID, if supplied and safe for this support channel>
Last observed task status: <status returned by the service, or unknown>
Status checked at: <date, time, and time zone, or not checked>

Record the status exactly as the service returned it. If an ID was not supplied or a status has not been checked, leave that uncertainty explicit; do not infer that the task succeeded or failed. Thanks to officialmailkr's comment for suggesting separate fields for this handoff.

If the original task ID is available, use the service's documented status query to inspect that task. Keep the task ID and the time of the first submission with the report. Avoid submitting the same paid operation repeatedly while its outcome is unknown.

If no task ID was returned, record that uncertainty and inspect the available request, task, or usage records through the appropriate authorized channel. Follow the service's retry guidance before attempting another paid operation. Agree on a small reproduction budget where a new test is necessary.

Watch the timeout handoff in 45 seconds

This silent visual checklist covers a returned task ID, a submission timeout without an ID, and a finished result that will not download. It uses English on-screen text, with English and Simplified Chinese subtitles available in the player settings.

Watch the timeout checklist on YouTube.

Use it alongside the reports below: keep the original ID and timestamps when available, record an unknown outcome explicitly, and follow the service's documented status and retry rules.

Two timeout reports, two different next steps

These fictional JSON records are examples for a support ticket, not request bodies for an API. The field names are local reporting choices, and running is an illustrative status: copy the actual status returned by your service. All identifiers below are placeholders.

Case A: the submission returned a task ID, but the local waiting deadline expired. A later status query returned running.

{
  "first_submitted_at": "2026-10-01T09:00:00Z",
  "original_task_id": "EXAMPLE-TASK-001",
  "last_observed_task_status": "running",
  "status_checked_at": "2026-10-01T09:01:00Z",
  "client_observation": "The local waiting deadline expired.",
  "next_step": "Check the original task using the documented status query."
}

Here, the task ID and the last response are useful evidence. Continue checking the same task according to the service's documented polling interval and limits. The expired local deadline is not a reason to create another paid task, and a running response is not evidence that a usable result already exists.

Case B: the submission connection timed out before a task ID arrived. No task status has been checked.

{
  "first_submitted_at": "2026-10-01T10:00:00Z",
  "original_task_id": null,
  "last_observed_task_status": null,
  "status_checked_at": null,
  "local_reference": "LOCAL-EXAMPLE-002",
  "client_observation": "The submission connection timed out before a task ID was received.",
  "next_step": "Reconcile the submission outcome before deciding on another request."
}

The local reference helps your team find its own incident record; it is not a server-issued task ID and must not be passed to a task query as though it were one. Use an authorized request or task-history lookup if the service provides one. If it does not, send the sanitized submission evidence through the approved support route and follow that service's retry guidance.

A missing item in a paginated, filtered, delayed, or incomplete history view does not prove that no task was created. Record the lookup's time window and limits instead of turning “not found in this view” into “safe to submit again.” Use idempotency keys only when the service documents their scope and reuse rules; inventing a key does not make a request safe to replay.

Keep unobserved values as null or explicitly unknown. Do not fill in a success or failure status from the passage of time. Before sending either report, apply the attachment review above; a structured JSON record is not automatically redacted.

When the polling wait exceeds your local budget

Consider a different fictional case: you have the original task ID, but no task status has been observed. A status query returns HTTP 429 with the numeric header Retry-After: 10, while this local monitoring run has only 5 seconds left.

Record	Value in this example
Original task ID	`EXAMPLE-TASK-01` (placeholder)
Last observed task state	Unknown
Status-query response	HTTP `429`; `Retry-After: 10` seconds
Remaining local monitoring budget	5 seconds
Local monitoring outcome	Paused; keep the original task ID

The next permitted check falls outside this monitoring run's budget. Pause the local monitor; do not shorten the 10-second wait to 5 seconds. Pausing local monitoring does not cancel the task or prove that it failed. The query limit does not authorize a new submission.

Keep the query response and its observation time separate from the last task state and the time that state was observed. If an earlier successful query returned pending or running, retain that earlier state with its original timestamp; a later 429 does not replace it with failed, paused, or a fresh state observation. In this example there was no earlier state, so it remains unknown.

If monitoring later resumes, use the same original task ID and the service's current polling rules, including any still-applicable wait. Reaching the end of Retry-After does not guarantee task completion or a successful next query. The field names and values here are local support notes, not a service's API contract.

The 47.4-second narrated example uses fictional inputs and locally synthesized English speech. Simplified Chinese captions are available. English automatic captions may misrecognize terms; the video description includes the complete English and Chinese transcripts.

Open the polling-budget example on YouTube.

Record output acceptance separately from task success

Case C: a status query reports success, but nobody has inspected the output. Keep the result check open until someone actually performs it. This fictional ticket extends the reporting format above; succeeded is illustrative, so preserve your service's actual status wording in a real report.

{
  "first_submitted_at": "2026-10-01T11:00:00Z",
  "original_task_id": "EXAMPLE-TASK-003",
  "last_observed_task_status": "succeeded",
  "status_checked_at": "2026-10-01T11:01:00Z",
  "output_check": "not_checked",
  "output_checked_at": null,
  "acceptance_evidence": null,
  "next_step": "Open the original result and check the agreed output requirements."
}

Record output_checked_at only after a person actually inspects the result. Add what was checked and a sanitized evidence reference, such as an approved review note. Use separate local outcomes for usable, unusable, and not checked; a task-success response alone cannot fill those fields.

If downloading fails or the output fails acceptance, retain the original task reference while investigating access, file format, or content quality. Follow the service's retry guidance before another generation. Keep credential-bearing result URLs out of the ticket.

Watch the 45-second Python record-validation demo. It uses a separate four-field local format to classify three fictional records and reject one inconsistent record. The silent video offers English and Simplified Chinese captions. Local validation does not query the server or authorize a new submission.

Change one thing, then record the result

Use the evidence to choose the next check. If the system address works while a custom domain fails, investigate that domain's DNS and certificate state. If the website works and the API request fails, check the specific service's key, available credits, request path, parameters, and error documentation.

Record each change and its result. Changing the domain, credentials, request body, and client library at the same time makes it difficult to learn which change mattered.

Close the ticket with the confirmed cause, the change that resolved it, and the evidence from the successful check. Keep credentials out of the resolution note too. This gives the next operator a usable record and helps identify repeated problems.

For the white-label workflow used here, the official launch and troubleshooting checklist covers the wider customer journey. Use the official support route for account-specific questions, and review the information before sending it.

Setting up a branded AI API portal: a practical launch checklist

Germey — Sun, 11 Oct 2026 17:34:12 +0000

Building a useful AI API service involves more than exposing endpoints. Your customers also need somewhere to find the right capability, understand the purchase flow, read integration instructions, and reach support.

This walkthrough covers setting up a branded developer portal with Ace Data Cloud's white-label API Platform. It focuses on the decisions that make the portal useful for customers: catalogue, documentation, branding, domains, and a verifiable first-use path.

Disclosure: this is a product guide from the Ace Data Cloud team. The examples use our public YourBrand demo; they are configuration examples, not customer revenue claims.

Watch the setup walkthrough

This 91-second walkthrough shows the configuration screens for branding, services, pricing, documentation, and domains. English and Simplified Chinese captions are available in the player settings.

Watch the full API Platform setup demo on YouTube.

1. Start with the customer and their first task

Choose a concrete audience before building a broad catalogue. A software agency integrating image generation into client applications needs a different starting point from a community building music workflows.

For a first version, write down:

Who will use the portal?
Which task should they be able to complete first?
Which services do you understand well enough to support?
Where should questions about accounts, orders, or integration go?

This gives you a practical way to decide what belongs on the homepage and which documentation should appear first.

2. Create the portal and configure the brand

In the Platform console, open Site Management, choose Create, and enter a site name and subdomain prefix. The current prefix format is 3–32 lowercase letters, digits, or hyphens; it must begin and end with a letter or digit and cannot contain consecutive hyphens.

Start with the system-provided address. In the site's management screen, configure the name, description, logo, and favicon. Check the site in a private browser window so you see what a customer sees.

The step-by-step API site guide includes the current forms and screenshots.

3. Organise services and documentation around that first task

Use the service and documentation settings to organise the portal. Adjust display names, descriptions, ordering, and the visible catalogue where those options are available.

For each service you feature, a customer should be able to answer:

What does it do?
Where are the usage and pricing details?
How do I get from this page to the integration instructions?
What should I provide to support if a request fails?

A visible catalogue entry is a discovery surface. Hiding an entry is a display decision; it should not be treated as revoking underlying API access.

You can inspect the public YourBrand API demo before choosing a catalogue structure.

4. Treat pricing, customer attribution, and earnings as separate checks

A site can use site-wide pricing overrides and supported service-specific overrides. A service-specific setting takes priority; it is not another percentage to stack on top of the site-wide override.

Customer purchase price and the operator's final earnings are separate records. Earnings depend on eligible orders, customer attribution, applicable distribution rules, and adjustments such as refunds. Example markup values in a demo are not a quote or a promise of profit.

Before promoting a commercial offer, confirm the current customer attribution and earnings rules and verify the relevant order records.

The white-label product uses a shared account, balance, and package system. Plan your customer explanation around that actual model; branding does not create a separate user database or an independently isolated billing stack.

5. Add domains after the system address works

The website domain and API domain serve different customer needs. Configure the ones your product requires, then follow the current DNS and certificate instructions.

Allow time for DNS and certificate processing. A successful site creation does not mean a new custom domain is already active.

After domain setup, repeat the same customer checks you performed on the system address: homepage, catalogue, documentation, sign-in, and the published integration route.

6. Validate the full customer journey

Before inviting a wider audience, walk through the launch sequence:

Step	Evidence to keep
Open the site as a visitor	Correct brand, clear primary service, working support link
Follow the documentation	A customer can locate the next integration step
Check registration attribution	The actual new account is attributed as intended
Make an intentional small purchase or request	Correct order, credit, and usage records where applicable
Inspect the operator's records	Eligible earnings follow the current rules

Real generation and payment checks can incur charges, so select an appropriate small test and inspect the actual records. A successful API request and an earnings entry are different outcomes; one is not proof of the other.

If a launch check fails, use the API support-ticket template to record the failing step, time, sanitized error, and non-secret request or task ID before contacting support. The companion guide also covers asynchronous timeouts and checking credentials, redirect URLs, and verbose logs before sharing evidence.

Once the first path works, keep the initial catalogue focused and add services based on customer demand. Maintain a clear support route and review usage, repeat purchases, and support effort before expanding the offering.

Keep a launch handoff record

A useful handoff lets the next person see what was checked, which route was used, and what remains open. Record each result as pass, fail, or not checked. A blank field is not a pass, and one successful test does not certify every customer, network, or service.

Copy this record for one intended customer journey. Use an authorized test account; keep private evidence in an approved location and share only the references appropriate to the recipient.

Purpose / first customer task:
Website / API hostname:
Client / network / test time:
Account reference (no secrets):
DNS / TLS result + evidence:
HTTP route result + evidence:
Allowed operation + result:
Denied operation + result:
Usage / order check + evidence:
Attribution / reward check:
Open issue + next owner:
Next check / acceptance scope:

For example, if DNS and TLS pass but the application returns 404, record the route result as failed and any unperformed credential tests as not checked. The transport result does not establish the route or credential scope. Conversely, opening the homepage does not prove that the API hostname is ready.

Use the companion guide for the layer you actually need to inspect:

Hostname or connection: the DNS and TLS probe verifies transport without sending an API key.
Credential scope: the permission test matrix separates visible catalogue entries from allowed and denied operations.
An unresolved request: the support handoff template helps preserve the original task reference and remove secrets from evidence.

Before another paid test, check the current service price and define the small operation you intend to run. Keep API success, usage or order reconciliation, and customer attribution or rewards as separate observations. A team handoff record does not create a spending limit or replace the platform's records.

Explore the product

If your customers want to integrate AI into an application, begin with the API Platform creation guide.

If they want to create directly in a browser, the Studio white-label guide covers the other product route.

For standard product or account questions, use the official support page.

Getting Started with the Ace Data Cloud TypeScript SDK

Germey — Sun, 11 Oct 2026 01:11:53 +0000