DEV Community: Germey

How to Build an Image Generation and Editing Workflow with the Seedream Images API

Germey — Sat, 01 Aug 2026 01:03:43 +0000

If you have ever tried to add image generation to a real product, you know the hard part is not only the prompt — it is designing a request shape, handling long-running jobs, and returning a usable image URL to the rest of your app.

In this guide, we will build a practical mental model for using the Seedream Images API through Ace Data Cloud. The goal is simple: send a prompt, optionally pass one or more input images for editing, and receive a generated image result that your backend can store, display, or pass to another workflow.

What you can do

The Seedream Images endpoint is useful when your application needs image generation or image editing from a structured API call. The documented endpoint is:

Base URL: https://api.acedata.cloud
Endpoint: POST /seedream/images
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

At the smallest level, a generation request uses action, model, and prompt:

{
  "action": "generate",
  "model": "doubao-seedream-5-0-260128",
  "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro."
}

The model string matters. For example, the docs use the complete model name doubao-seedream-5-0-260128; abbreviations such as doubao-seedream-5.0-lite are not accepted.

The same API family also supports richer fields depending on the model you choose: image, size, response_format, watermark, output_format, async, callback_url, and model-specific fields such as seed, guidance_scale, stream, sequential_image_generation, or tools.

Make your first request with curl

Here is the basic curl request I would start with in a backend prototype:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer ${token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro."
  }'

A successful response includes a task identifier, a trace identifier, and a data array with the image result:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

For an application, the important fields are success, task_id, trace_id, data[].image_url, data[].prompt, and data[].size. I usually persist task_id and trace_id together, because they make debugging much easier when a user reports a missing image.

Choose the right model and size

The docs list several supported model strings, including doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828, doubao-seedream-3-0-t2i-250415, and doubao-seededit-3-0-i2i-250628.

Not every field works with every model, so treat the model as part of your API contract. For example, doubao-seedream-5-0-pro-260628 is documented as a flagship single-image model and does not support sequential_image_generation, stream, or tools. The seed field is only supported by doubao-seedream-3-0-t2i-250415.

The size field can be specified in two ways: a preset such as 1K, 2K, 3K, or 4K when the selected model supports presets, or an explicit pixel size such as 2048x2048. Preset support varies by model, so if you are building a UI, it is safer to make the allowed size options depend on the selected model rather than exposing one global dropdown.

Editing an existing image

For image editing, include the image field with the URL or Base64 input image. The documentation says some Seedream models support single or multiple image inputs, while doubao-seededit-3-0-i2i-250628 supports only a single image input and doubao-seedream-3-0-t2i-250415 does not support the image parameter.

A typical edit payload looks like this:

{
  "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": [
    "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"
  ],
  "size": "2K",
  "watermark": false
}

This is the pattern I would use for product mockups, image variations, or controlled visual transformations: keep the source image in object storage, pass its URL in image, and make the prompt describe only the intended edit.

Handle long-running jobs cleanly

Image generation can take about one to two minutes. If you do not want a client request to stay open, the API supports asynchronous handling.

There are two documented approaches:

Provide callback_url. The API returns a task_id, then POSTs the final JSON result to your callback URL when the job finishes.
Set async to true without a callback URL. The API returns a task_id, and your application polls /seedream/tasks to fetch the final result.

A simple production pattern is to create an internal image_jobs table with columns like task_id, trace_id, status, prompt, and image_url. Your initial request creates the row. Your callback handler or polling worker updates it when data[].image_url arrives.

Error handling

The docs show errors such as 400 token_mismatched, 400 api_not_implemented, 401 invalid_token, 429 too_many_requests, and 500 api_error. A typical error response includes success: false, an error.code, an error.message, and a trace_id.

In practice, I would map these into three buckets: fix the request, refresh or check credentials, and retry later. Always log trace_id; it is the field you will want when debugging a failed generation.

Where this fits

This is not just a “generate me a picture” endpoint. With prompt, image, model-specific size handling, async execution, callbacks, and traceable task IDs, you can wire Seedream into a real builder workflow: product imagery, internal creative tooling, design previews, or background asset generation.

The full API reference is available in the Ace Data Cloud documentation: Seedream Images API integration guide.

How to Generate Short Videos from Claude.ai with a Seedance MCP Connector

Germey — Fri, 31 Jul 2026 01:11:50 +0000

Sometimes the fastest way to prototype a video idea is not to open a separate generation dashboard, but to let your assistant create and poll the task while you stay in the conversation.

This guide shows how the Seedance MCP connector works inside Claude.ai, based on the Ace Data Cloud documentation. The workflow is practical: add one remote MCP URL, authorize with OAuth, ask Claude to list available models and resolutions, then generate a short video and poll the task until a URL is returned.

What you can do

Seedance is ByteDance’s Doubao video generation family, exposed here through a remote MCP server. Once connected to Claude.ai, the documented tools include:

Tool	Purpose
`seedance_generate_video`	Generate a video from a text prompt
`seedance_generate_video_from_image`	Animate an image into a video
`seedance_get_task`	Query a single generation task
`seedance_get_tasks_batch`	Query multiple tasks together
`seedance_list_actions`	List supported actions
`seedance_list_models`	List available models
`seedance_list_resolutions`	List valid resolutions

The important part is that Claude can call the list tools first, choose valid values, submit a task, and then poll with seedance_get_task. You do not need to manually copy model names between pages.

How it works

Claude.ai supports custom MCP connectors. For Seedance, the connector uses OAuth direct connection, so the guide does not require copying an API token into Claude. You add a custom connector with this URL:

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

In Claude.ai, open settings for connectors, add a custom connector, and use a name such as:

Seedance

Then fill the URL field with:

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

After clicking connect, Claude redirects to Ace Data Cloud for OAuth authorization. Once approved, the connector appears in Claude with the Seedance tools listed above.

Set tool approval intentionally

Video generation usually involves more than one tool call. A careful prompt may ask Claude to:

call seedance_list_models,
call seedance_list_resolutions,
submit with seedance_generate_video,
poll with seedance_get_task.

The source guide recommends setting tool approval to “Always allow” for the connector if you are comfortable with the workflow. Otherwise, Claude may ask for confirmation several times during one generation. If you are testing a new prompt or model, leaving approvals on can still be a reasonable safety choice.

Run a minimal text-to-video test

A good first prompt should be specific about cost, duration, and resolution constraints without pretending you already know every valid option. The documentation uses this style:

Use Seedance to generate one short video. First list models and resolutions, pick the FASTEST/CHEAPEST model (e.g. lite/fast variant) and the LOWEST resolution. Use the SHORTEST duration (4-5 seconds). Subject: a fluffy white kitten chasing a red leaf falling in a sunny garden, side view, simple background.

In the documented run, Claude first called seedance_list_models and seedance_list_resolutions, then selected:

doubao-seedance-1-0-pro-fast-251015
480p
4 seconds
16:9
24fps

Then it submitted the generation with seedance_generate_video and used seedance_get_task to wait for the result.

That order is worth copying. Instead of hard-coding values that may become stale, let the assistant ask the MCP server for valid options first.

Animate an existing image

The same connector also supports image-to-video generation. The documented tool for that is:

seedance_generate_video_from_image

A prompt can be as direct as:

Take this image https://cdn.acedata.cloud/foo.png and animate it with Seedance fast model: slow zoom-in, soft wind, 4 seconds, 480p.

This is useful for product mockups, social clips, or turning a static storyboard frame into a short motion test. The important fields to keep explicit are the source image URL, motion direction, duration, and resolution.

Compare variants before committing

When you are not sure which model variant fits a scene, use Claude as a small experiment runner. For example:

Generate the same prompt "a samurai walking through bamboo forest in mist" with Seedance pro AND fast variants at 720p, 5 seconds, and tell me which one looks better.

Claude can call seedance_list_models, submit separate tasks, then compare the returned videos. This is especially useful during prompt exploration, where you care more about learning what works than producing the final asset in one shot.

Batch a few lightweight ideas

For early ideation, batch generation can save time. The documented batch-style prompt is:

Generate 3 Seedance videos in parallel: 1) puppy on beach, 2) hot air balloon at sunrise, 3) coffee being poured. All 480p, 4s, fast model. Then return all three URLs.

Here Claude can submit multiple tasks and use:

seedance_get_tasks_batch

to check them together. I would keep batch prompts small at first: three short clips are easier to review than ten, and the feedback loop stays manageable.

A builder-friendly workflow

A practical workflow for short-form video prototyping looks like this:

Start with 480p and 4 seconds.
Ask Claude to list models and resolutions before choosing values.
Generate one simple shot with clear subject, motion, background, and framing.
Review the result and change only one variable at a time.
Batch two or three variants once the prompt direction is stable.

This keeps the assistant useful without turning the process into a black box. You still decide the creative direction; the MCP connector handles valid parameters, task submission, and polling.

Full setup reference: https://platform.acedata.cloud/documents/claude-mcp-seedance

How to Poll Async Image Tasks with the OpenAI Tasks API

Germey — Thu, 30 Jul 2026 01:08:36 +0000

When an image request takes longer than a comfortable HTTP timeout, the cleanest user experience is not to keep the browser waiting — it is to submit the job, store a task ID, and let your backend check the result later.

That is the job of the OpenAI Tasks API in Ace Data Cloud: it lets you retrieve tasks created by image requests that were submitted in callback mode.

What you can do

The Tasks API is designed for asynchronous image workflows. You use it when an original image generation or editing request includes a callback_url. In that mode, the image interface accepts the request and immediately returns a task_id. Later, you can query the task by id, or by trace_id if you passed your own custom tracking identifier.

The key details are:

Endpoint: POST https://api.acedata.cloud/openai/tasks
Headers:
  accept: application/json
  authorization: Bearer {token}
  content-type: application/json
Supported actions:
  retrieve
  retrieve_batch

There is one important constraint: task records are only persisted when the original image request includes callback_url. Synchronous, non-callback calls do not create queryable task records.

How it works

Think of the flow as a small job system:

Your app submits an image request with a callback_url.
The image endpoint immediately returns a task_id.
You store that task ID with your internal job record.
Your worker or backend calls POST /openai/tasks with action: retrieve.
When the task has a response, you read the final image URL from response.data[].

A returned task can include fields such as id, trace_id, type, application_id, user_id, credential_id, created_at, finished_at, duration, request, and response. That is enough to build both a user-facing status page and an internal debugging trail.

Retrieve one task by task ID

For most apps, the simplest approach is to use the task ID returned by the original submission response. You do not need to invent a custom trace_id unless you want to map tasks to your own business identifier.

curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434"
  }'

If the task exists and has completed, the response follows this shape:

{
  "id": "7489df4c-ef03-4de0-b598-e9a590793434",
  "trace_id": "my-custom-trace-001",
  "type": "images",
  "created_at": 1763142607.967,
  "finished_at": 1763142637.404,
  "duration": 29.437,
  "request": {
    "model": "gpt-image-1",
    "prompt": "A cat sitting on a table",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      { "url": "https://platform.cdn.acedata.cloud/openai/...png" }
    ],
    "success": true
  }
}

If no task matches, the API returns an empty object:

{}

That empty-object behavior is useful in a polling loop: treat it as “not found or not available yet,” not as a completed image.

Submit and poll from Python

Here is the end-to-end shape for a backend worker. The image request includes callback_url, so the task is persisted and can be queried later.

import os
import time
import requests

API = "https://api.acedata.cloud"
HEADERS = {
    "authorization": f"Bearer {os.environ['ACEDATA_API_KEY']}",
    "content-type": "application/json",
}

submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "A watercolor style cat sitting on a table",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()

print("submitted:", submit)
task_id = submit["task_id"]

while True:
    task = requests.post(
        f"{API}/openai/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
    ).json()

    if task and task.get("response"):
        print("finished:", task["response"])
        break

    time.sleep(3)

In a real app, I would not keep this loop inside a request handler. Put it in a worker, queue job, scheduled function, or background task. Store task_id, the submitted prompt, the user ID in your own system, and the final response.data[] when it arrives.

Batch query for dashboards and recovery

The second action is retrieve_batch. It is useful when you need to recover multiple jobs, build an admin dashboard, or query by your own tracking IDs.

The request can include fields such as ids, trace_ids, application_id, user_id, type, offset, limit, created_at_min, and created_at_max. At least one lookup dimension is required: for example ids, trace_ids, application_id, user_id, or a created-at time window.

curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "trace_ids": ["my-trace-001", "my-trace-002"]
  }'

A batch response contains items and count, so your UI can render a task table without designing another aggregation layer first.

Practical implementation notes

A few details make this flow much easier to operate:

Save both task_id and trace_id when available.
Treat finished_at as the signal that a task has reached a terminal state.
Read final images from response.data[], not from the original submission payload.
Use duration for basic latency monitoring.
Remember that old task records may be cleared after the platform retention period.
Poll gently. The Tasks interface itself does not incur charges, but your worker should still avoid noisy loops.

This pattern keeps the image-generation UX predictable: users submit work, your system tracks the task, and the final image appears when the callback or polling result is ready.

For the complete field reference, see the OpenAI Tasks API Integration Guide.

How to Upload Files to a CDN Before Calling AI Media APIs

Germey — Tue, 28 Jul 2026 01:07:14 +0000

When you build AI media workflows, you quickly run into a small but annoying problem: many APIs want a public file URL, while your source asset is sitting on a local disk, in a temporary upload, or inside your own backend.

What you can do

The AceDataCloud platform file upload API is a small utility endpoint for turning a local file into a permanently accessible CDN URL. The uploaded file returns a file_url such as:

{
  "file_url": "https://cdn.acedata.cloud/qrd7gw.jpg"
}

That URL can then be passed into downstream APIs that expect URL inputs, for example fields like image_url, image_urls, or reference_url in media generation workflows.

This is not a general marketing feature; it is a practical glue step. If your pipeline needs to call an image, video, or music API that cannot read your local file directly, you upload once, get a URL, and pass that URL forward.

How it works

The upload endpoint belongs to the AceDataCloud Platform Management API, whose unified prefix is:

https://platform.acedata.cloud/api/v1/

The concrete endpoint is:

POST https://platform.acedata.cloud/api/v1/files/

The important request details are:

Authentication: account token in Authorization: Bearer ...
Content type: multipart/form-data, not JSON
Form field: file
Default single file limit: 28 MB
Response field: file_url

A minimal cURL request looks like this:

curl -X POST 'https://platform.acedata.cloud/api/v1/files/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c' \
  -F 'file=@./photo.jpg'

The response is intentionally small:

{
  "file_url": "https://cdn.acedata.cloud/qrd7gw.jpg"
}

The returned CDN URL is publicly accessible without authentication. That makes it convenient for machine-to-machine workflows, but it also means you should not upload sensitive data unless you have a clear retention plan.

Use case: prepare a base image for a generation pipeline

A common pattern is to let a user upload an image, store it briefly in your backend, then pass it to a generation API as a reference. Many APIs do not want base64 in those fields; they want a URL.

The platform file upload endpoint solves the transition:

Receive photo.jpg from the user or from an internal job.
Upload it to POST /api/v1/files/ as multipart/form-data.
Read data.file_url from the response.
Use that URL in the next API call.

The documentation gives examples such as using CDN URLs with Midjourney image_urls, Flux image_url, and Veo reference_url. The upload step is the same regardless of which downstream service you call next.

Python example

Here is the Python version from the same workflow, adapted as a small function. Notice that the request uses files=..., not a JSON body.

import requests

PLATFORM_TOKEN = "platform-v1-92eb****629c"


def upload_to_cdn(path: str) -> str:
    with open(path, "rb") as f:
        resp = requests.post(
            "https://platform.acedata.cloud/api/v1/files/",
            headers={
                "accept": "application/json",
                "authorization": f"Bearer {PLATFORM_TOKEN}",
            },
            files={"file": ("photo.jpg", f, "image/jpeg")},
            timeout=60,
        )

    resp.raise_for_status()
    data = resp.json()
    return data["file_url"]


file_url = upload_to_cdn("photo.jpg")
print("CDN URL:", file_url)

In a real service, you would keep PLATFORM_TOKEN in your secret manager or environment, not inside source code. The token shown above is a masked example from the docs.

Once you have file_url, the next request can reference it directly. The docs show the idea with a downstream image call:

# requests.post(
#     "https://api.acedata.cloud/midjourney/imagine",
#     json={"prompt": "...", "image_urls": [file_url]},
#     ...
# )

The key point is not the specific downstream model. The important contract is: local binary file in, stable CDN URL out.

Node.js example

For Node.js, use form-data and stream the file from disk:

const fs = require('fs')
const FormData = require('form-data')

const form = new FormData()
form.append('file', fs.createReadStream('./photo.jpg'))

const r = await fetch('https://platform.acedata.cloud/api/v1/files/', {
  method: 'POST',
  headers: {
    authorization: 'Bearer platform-v1-92eb****629c',
    ...form.getHeaders(),
  },
  body: form,
})

const data = await r.json()
console.log('CDN URL:', data.file_url)

One detail that often causes bugs: do not manually set Content-Type: multipart/form-data without the boundary. Libraries such as form-data generate the correct headers for you through form.getHeaders().

Error handling you should implement

There are three practical failures to handle:

400 with {"error":"No file provided"}: the request did not include the file field, or the field name was wrong.
401: the account token is missing or invalid.
413 with {"error":"File too large","max_bytes":...}: the file exceeds the default 28 MB limit.

In a backend service, I would treat these differently. A 400 is usually a developer or form-data bug. A 401 should alert you to configuration or secret rotation. A 413 is a product constraint: validate file size before upload and show the user a clear message.

Operational tips

A few details matter in production:

The returned file_url is permanent and publicly accessible, so avoid uploading secrets, private user files, or unreleased assets unless that is intended.
For bulk uploads, the docs recommend 2–4 concurrent uploads.
A single connection can reach around 10 MB/s, which is usually enough for image and short media preprocessing.
Because the endpoint expects a single file field, keep batch logic in your client rather than trying to send many unrelated files in one request.

Closing thoughts

This endpoint is useful because it removes a boring infrastructure step. Instead of standing up temporary object storage just to satisfy URL-based AI APIs, you can upload a file, receive file_url, and continue the workflow.

If you want the exact request and response reference, see the platform file upload documentation.

How to Upload Reference Audio for a Suno-Based Music Workflow

Germey — Mon, 27 Jul 2026 01:07:31 +0000

When you build music features, the first useful primitive is often not “generate a full song from scratch.” It is: take an existing reference track, upload it safely, extract the metadata you need, and keep the returned song ID for the next step in your workflow.

This guide walks through the Suno Upload Reference Audio API on Ace Data Cloud. The API is intentionally small: send a publicly accessible MP3 URL, receive an uploaded audio record, and use the returned audio_id later for secondary creation.

What you can do

The upload endpoint is:

Base URL: https://api.acedata.cloud
Endpoint: POST /suno/upload
Headers:
  accept: application/json
  authorization: Bearer {token}
  content-type: application/json

The request body has one input parameter:

{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
}

The important constraint is that audio_url must be a publicly accessible CDN address and support the .mp3 suffix. In other words, this endpoint is best used after your app has already placed the reference audio somewhere the API can fetch.

The response gives you a normalized audio object. The key field is data.audio_id, which is the song ID after upload. The response can also include extracted or generated context such as lyric, style, image_url, image_large_url, audio_url, title, and duration.

Step 1: Make the upload request

Here is the complete cURL call from the integration shape:

curl -X POST 'https://api.acedata.cloud/suno/upload' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
  }'

In a real application, replace the demo URL with a direct MP3 URL from your own storage or CDN. I would validate three things before calling the API:

The URL is reachable without user authentication.
The file is an MP3 URL, not a web page that embeds a player.
Your backend stores the original source URL before sending the request.

That third point matters because the returned data tells you what the platform produced, while the source URL tells you what your user originally provided.

Step 2: Read the response as a workflow object

A successful response has this general shape:

{
  "success": true,
  "task_id": "058f8450-3df4-4f8b-8b64-ebc2e59ed3bc",
  "data": {
    "audio_id": "00135f7d-cda1-4d70-b007-779f07143586",
    "lyric": "[Intro]\nHa-ha-ha-ha-ha-ha...",
    "style": "Upbeat bubblegum pop track with a high-energy electronic production style...",
    "image_url": "https://cdn2.suno.ai/image_00135f7d-cda1-4d70-b007-779f07143586.jpeg",
    "image_large_url": "https://cdn2.suno.ai/image_large_00135f7d-cda1-4d70-b007-779f07143586.jpeg",
    "audio_url": "https://cdn1.suno.ai/00135f7d-cda1-4d70-b007-779f07143586.mp3",
    "title": "up-d6c3970d-6db1-41e3-b966-90539c93678a",
    "duration": 131.16
  }
}

The fields I would persist are:

task_id for tracking the upload request
data.audio_id for later music generation or extension flows
data.audio_url for playback
data.duration for UI display and validation
data.lyric and data.style if your product lets users review or edit the extracted musical context

Treat the upload response as the “asset registration” step. After this, your app has an ID it can pass to later music-generation operations.

Step 3: Connect it to secondary creation

The document notes that once you have the song ID, you can use the Suno Audios Generation API to generate custom songs. The specific handoff is to pass action as upload_extend and use the returned audio_id as the reference song ID.

A clean backend abstraction might look like this:

uploadReferenceAudio({ audio_url }) -> { task_id, audio_id, lyric, style, audio_url, duration }

Then the next workflow step can accept audio_id without needing to know where the original file came from.

This separation helps a lot in product code. Uploading reference audio, reviewing extracted context, and generating a derivative song are different user actions. Keeping them separate makes the interface easier to debug and easier to retry.

Step 4: Design the user flow around constraints

Because the API expects a public MP3 URL, your user-facing flow should make that constraint obvious. A practical flow is:

User uploads an MP3 to your app.
Your backend stores it on a CDN or object storage bucket.
Your backend calls POST /suno/upload with the public audio_url.
Your app displays the returned title, duration, cover image, lyric, and style.
The user confirms whether to continue with a secondary creation step using audio_id.

If the upload fails, keep the original user file and source URL so the user does not have to start again. If the upload succeeds but later generation fails, you still have audio_id and can retry the downstream step.

A small but useful primitive

This endpoint is deliberately narrow, and that is what makes it useful. It does not ask you to model the entire music workflow in one request. It gives you one reliable bridge from an existing MP3 reference to an audio_id that can be used later.

For builders, that is a good boundary: one API call to register the reference, one stored ID for future work, and enough metadata to show users what was understood from their audio.

The full field reference is in the Suno Upload API documentation: https://platform.acedata.cloud/documents/suno-upload-integration

How to Add Flux Image Generation to Cursor with MCP

Germey — Sun, 26 Jul 2026 01:04:53 +0000

If you already live inside Cursor, the fastest image workflow is not another browser tab — it is asking your editor to generate or edit an image while it still has the context of the code, copy, and UI you are building.

What you can do

Flux MCP is a small but practical setup: it exposes Flux image tools to Cursor through the Model Context Protocol. Once configured, you can ask Cursor to create assets while you are working on a product surface, README, landing page, or design prototype.

The source document describes two available tools:

Tool	Use case
`flux_generate_image`	Text-to-image generation
`flux_edit_image`	Image editing

That means you can keep common builder tasks close to your project:

generate several visual directions for an empty state illustration;
refine the most promising image with a higher-quality pass;
edit an existing background or image without starting from scratch;
batch-generate a small set of consistent avatars or UI assets.

This is not meant to replace a full design system or a designer's review. It is most useful in the messy middle: when you need something concrete enough to unblock a UI decision, a prototype, or a draft.

How it works

Cursor can talk to MCP servers through a local project configuration file. For Flux, the documented server is an HTTP MCP endpoint:

https://flux.mcp.acedata.cloud/mcp

Authentication is passed with a bearer token in the Authorization header. The minimal Cursor configuration from the documentation is:

{
  "mcpServers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer yourToken"
      }
    }
  }
}

In a Cursor project, place this in:

.cursor/mcp.json

Replace yourToken with your Ace Data Cloud API token. The same source notes that a single token can be used across MCP servers, so you do not need a separate token just for Flux.

A practical security note: avoid committing .cursor/mcp.json if it contains a real token. Add it to .gitignore, or use a team-approved secret-management pattern if your workflow supports one.

Step 1: Configure Cursor

Create the MCP config file at the root of your project:

mkdir -p .cursor
cat > .cursor/mcp.json <<'JSON'
{
  "mcpServers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer yourToken"
      }
    }
  }
}
JSON

Then open Cursor and check that the MCP server is available in the editor's MCP/tooling area. The exact UI may change over time, but the important pieces are stable: server name flux, type http, URL https://flux.mcp.acedata.cloud/mcp, and the Authorization bearer header.

For other editors, the document points to similar configuration patterns: VS Code uses .vscode/mcp.json with the same configuration under servers, while Windsurf uses .windsurf/mcp.json under mcpServers.

Step 2: Generate quick visual directions

The best first use case is fast iteration. Suppose you are building an app screen with an empty state and the page currently feels unfinished. Instead of leaving a gray placeholder, ask Cursor for multiple directions:

Use flux-dev to quickly generate 3 different styles of "no data" empty state illustrations, trying flat, 3D, and hand-drawn styles.

The documentation describes Dev mode as the fastest path for trial and error. The point is not to get the final asset immediately. The point is to compare directions while you are still thinking about the component, the surrounding copy, and the audience.

Once one direction feels right, you can ask for a refinement pass:

Use flux-pro to refine the second image, increasing the resolution.

This two-step pattern keeps the workflow efficient: use a quick pass to find the visual idea, then spend the slower/high-quality step only on the candidate that deserves it.

Step 3: Edit an existing image

Image generation is useful, but editing is often more practical in real product work. Maybe a designer sent you a background image, but the center title needs to be changed for an English prototype. The documented tool for this is flux_edit_image.

A natural instruction might look like this:

Edit this image, changing the Chinese title in the middle to "Welcome to the Future."

This is where having the tool inside Cursor helps. You can keep the task connected to the current feature branch: the asset, the component copy, the README, or the issue you are working from.

Be specific when you ask for edits. Mention what should change, what must stay the same, and where the change should happen. For example: “keep the background and lighting, only replace the centered title text.” That reduces accidental regeneration.

Step 4: Batch small assets

Another documented scenario is batch image generation. If your app needs default avatars for a user system, you can ask for a consistent set in one go:

Generate 5 minimalist geometric style avatars, each with a different color combination, circular cropped.

The source document notes that the count parameter can generate multiple images at once, which is useful when consistency matters. For UI work, I like to include constraints such as “same visual style,” “different color combination,” and “circular cropped” so the output is easier to drop into a mockup.

A few builder tips

Treat Flux MCP as an iteration tool, not a magic finalizer. Start broad, compare options, then refine. Keep prompts close to the product context: who the screen is for, where the asset appears, and what should not change. And when a generated image becomes part of production work, review it the same way you would review copy or code.

If you want the original setup details, the Ace Data Cloud document is here: https://platform.acedata.cloud/documents/cursor-mcp-flux

Integrating Claude Code with Veo MCP: Generate HD AI Videos from the Terminal

Germey — Fri, 24 Jul 2026 01:03:18 +0000

When I need a short product demo or a visual explanation for a README, the slow part is rarely the idea. The slow part is leaving the terminal, opening another tool, and translating a developer task into a video-editing workflow.

This guide walks through a terminal-first setup: connecting Claude Code to the Veo MCP server so you can ask for short AI-generated videos in plain language while staying inside your project workspace.

The source workflow comes from the Ace Data Cloud documentation for Claude Code + Veo MCP. Veo is described there as an AI video generation model from Google, with support for 1080p output and video generation with accompanying audio. In practice, the interesting part for builders is not just the model. It is the MCP layer: Claude Code can call a video tool directly from a coding session.

What you can do

After the MCP server is connected, Claude Code can use two Veo tools:

veo_generate_video: generate video from text or images
veo_generate_video_with_audio: generate video with audio

That covers a few practical cases that come up in engineering work:

A small app demo, such as a phone screen showing weather data while the background changes from sunny to rainy
A README animation, such as data moving from an input box to a result panel through three processing nodes
A terminal-style video with audio, such as code being typed on a black background, keyboard clicks, a successful compile, and a green check mark

The point is not to replace careful design work. It is to make lightweight visual assets easier to prototype when you already know the scene you want.

How it works

The MCP server URL used by this workflow is:

https://veo.mcp.acedata.cloud/mcp

Claude Code connects to it over HTTP, and authentication is passed with an Authorization header:

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

A small but important detail: the -H flag must be uppercase. In the Claude Code command, lowercase -h means help, not an HTTP header. If the connection looks like it is not receiving your token, check this first.

You can get the token from the Ace Data Cloud platform after logging in. The same token is used for the MCP server connection, so Claude Code can authenticate when it calls the Veo tools.

Choose the right configuration scope

Claude Code lets you decide where the MCP configuration should apply. If you omit -s, the default scope is local, which only applies to the project directory where the command runs.

The documented scopes are:

Scope	Command parameter	Config file	Applies to
`local`	no `-s` or `-s local`	`~/.claude.json`	only the project directory where the command runs
`user`	`-s user`	`~/.claude.json`	all projects for the current user
`project`	`-s project`	`.mcp.json` in the project root	the current project

For a personal experiment, local scope is usually enough. For a tool you expect to use across many repositories, -s user is convenient. For a team project, -s project can make sense because the config lives in the project root.

One warning: do not commit real tokens to a public repository. If you use project scope and share the config through git, use an environment variable placeholder such as ${ENV_VAR} instead of a real bearer token.

Verify the connection

After adding the MCP server, run:

claude mcp list

You are looking for the veo server to show a connected status:

veo  ✓ Connected

If it does not connect, I would check three things in this order:

Is the server URL exactly https://veo.mcp.acedata.cloud/mcp?
Did you use uppercase -H for the authorization header?
Is the token present after Bearer and not accidentally wrapped or truncated by your shell?

Try a few builder-focused prompts

Once the server is connected, you do not need to write a separate API request by hand. You can ask Claude Code to use the Veo tool from the current session.

For an app demo:

I am developing a weather app. Generate a demo video: the phone screen shows weather information, and the background transitions from sunny to rainy.

For documentation:

Generate an animation for the README: data flows from the input box on the left to the result panel on the right, passing through three processing nodes in the middle.

For a terminal video with audio, explicitly ask for the audio-capable tool:

Use veo_generate_video_with_audio to generate a short video with audio: code is typed automatically on a black background, keyboard clicking sounds play, compilation succeeds, and a green ✓ appears.

These prompts are intentionally concrete. In my experience, video prompts work better when they describe the subject, motion, environment, and expected ending state instead of only saying “make a cool demo.”

Where this fits in a developer workflow

I would use this workflow for first-pass assets: demo clips for a landing page draft, quick README visuals, internal prototypes, or short explainers for a feature branch. The value is that the generation step sits next to the code and docs you are already editing.

If you want the exact setup reference, the original Ace Data Cloud doc is here: https://platform.acedata.cloud/documents/claude-code-mcp-veo

How to Generate and Edit Images from Claude with a NanoBanana MCP Connector

Germey — Tue, 21 Jul 2026 01:05:01 +0000

You are writing in Claude, planning a blog post or product concept, and suddenly need a quick image: not a separate design session, just a usable visual artifact from the same conversation.

With a NanoBanana MCP connector, Claude can call an image generation and editing tool directly, then return the resulting image link back into the chat.

What you can do

The source document describes a Claude.ai web integration for NanoBanana MCP, a remote MCP server that wraps Google Gemini 2.5 Flash Image series capabilities behind tools Claude can call.

Once connected, Claude can:

Generate images from text descriptions with nanobanana_generate_image.
Edit images, make partial modifications, or apply style transfers with nanobanana_edit_image.
Query a single task with nanobanana_get_task.
Query multiple tasks in batch with nanobanana_get_tasks_batch.

That tool split is important. Image generation often behaves like an asynchronous workflow: submit a prompt, receive a task, query the task, then display the final image URL. In a normal API integration you would write that orchestration yourself. With MCP attached to Claude, the assistant can do the submit-and-poll loop from the chat.

How it works

Claude.ai supports custom connectors. For NanoBanana MCP, the connector is added from Claude's settings:

https://claude.ai/customize/connectors

From there, choose Add custom connector and configure these fields:

Field	Value
Name	`NanoBanana`
URL	`https://nanobanana.mcp.acedata.cloud/mcp`

The document notes that Claude.ai uses OAuth direct connection for this flow, so there is no API token to copy into Claude. On first connection, Claude redirects to Ace Data Cloud for authorization. After allowing access, Claude returns to the connector page and discovers the available tools.

A practical detail from the source guide: set each tool to Always allow if you plan to use it frequently. Image generation commonly triggers more than one tool call, such as a generation call followed by a task query. If every call requires a confirmation dialog, the workflow feels much less conversational.

Start with one concrete prompt

A good first test is a single, specific English prompt. The source document uses this example:

Use NanoBanana to generate one image: a cute corgi astronaut floating in space, soft pastel nebula background, photorealistic, 16:9.

Claude's job is not just to repeat the prompt. It decides which MCP tool to call, passes the prompt and aspect ratio, receives the task information, calls nanobanana_get_task, and returns the final image link when the task is complete.

For best results, give the model enough visual constraints:

Subject: a cute corgi astronaut
Scene: floating in space
Background: soft pastel nebula background
Style: photorealistic
Aspect ratio: 16:9

This makes the output easier to reuse as a blog cover, social image, or design placeholder.

Edit an existing image in the same thread

The connector also supports image editing through nanobanana_edit_image. The source guide gives this follow-up prompt:

Take that corgi image and replace the helmet with a giant donut.

The useful pattern here is continuity. Claude can refer to the previous image URL from the conversation and pass it into the edit workflow. Instead of manually downloading and uploading files between tools, you can keep the iteration inside the same thread.

This is especially useful for small creative changes:

Replace one object while keeping the scene.
Make a partial modification to a product concept.
Try a different visual theme after the first generation.
Turn a rough prompt into several refinements before choosing a final image.

The workflow still needs human review. Treat each result as a candidate, not an automatic final asset.

Generate variations instead of over-editing one image

Sometimes the better move is not to keep editing one result. The guide shows a batch-style request:

Generate 4 variations of that corgi astronaut, each in a different mood.

Claude may issue several generation calls and then use nanobanana_get_tasks_batch to retrieve the results together. This is a good way to explore composition before committing to edits.

A builder-friendly workflow looks like this:

Ask for 3–4 variations with clear differences.
Pick the strongest direction.
Use nanobanana_edit_image for targeted changes.
Save the final CDN image URL for your article, slide, or prototype.

The source document notes that returned images are hosted on Ace Data Cloud's CDN, so the image links can be pasted into blogs, slide decks, or design drafts.

Use it as part of a broader MCP workflow

NanoBanana is most helpful when it becomes one tool in a larger assistant workflow. For example, you can ask Claude to draft a blog outline, generate a cover image, then revise the prompt until the image matches the article angle.

The same connector can handle both generation and editing, while task-query tools handle result retrieval. That makes the chat feel less like a prompt box and more like a lightweight creative pipeline.

A few habits help:

Keep prompts specific and visual.
Include the target aspect ratio, such as 16:9, when you know the destination.
Use English prompts when you want more stable adherence, as suggested by the source guide.
Set tool permissions intentionally instead of approving every call one by one.

Closing thoughts

This setup is useful because it removes the context switch. You stay in Claude, describe the image you need, and let the MCP connector handle generation, editing, and task retrieval.

It is not a replacement for design judgment, but it is a practical way to move from idea to usable visual draft while you are already thinking through the work.

Original setup reference: https://platform.acedata.cloud/documents/claude-mcp-nano-banana

Getting Started with AceKit for Coding Agents

Germey — Mon, 20 Jul 2026 16:28:10 +0000

Coding agents are great at editing files, but they often stop when a task needs the outside world: generating an image, searching the web, shortening a link, or calling a model-specific API.

AceKit is a small installer that wires Ace Data Cloud capabilities into coding agents such as Claude Code, Codex CLI, Cursor, Gemini, and OpenCode. Instead of manually reading multiple API docs and writing one-off scripts, you install a skill toolkit once, provide a token, and let the agent follow each skill’s SKILL.md instructions.

This guide walks through the practical setup and then looks at what happens behind the scenes.

What you can do

After installation, your agent can load skills for tasks that normally sit outside plain code editing. The document lists examples such as:

generating a README cover image
turning a script into a short video
generating background music
searching Google SERP in real time
shortening a long link into a surl.id URL

The current skill list shown in the document includes:

acedatacloud-api   ai-chat            face-transform     fish-audio
flux-image         google-search      hailuo-video       kling-video
luma-video         midjourney-image   nano-banana-image  producer-music
seedance-video     seedream-image     short-url          sora-video
suno-music         veo-video          wan-video

That list can change over time, so use npx acekit list to inspect the current set on your machine.

How it works

AceKit is the front door. It detects supported coding agents, installs a set of agent skills, and uses one Ace Data Cloud token for authentication.

The documented requirements and fields are straightforward:

Node.js 18+
install command: npx acekit
optional environment variable: ACEDATACLOUD_API_TOKEN
Claude Code skill path: ~/.claude/skills
Codex CLI skill path: ~/.agents/skills
Cursor / Gemini / OpenCode skill path: ~/.agents/skills

Each installed skill includes a written SKILL.md manual. That matters because the agent does not need to guess how a capability works. The skill can describe authentication, parameters, polling, retries, and how to return the final artifact.

Step 1: Prepare the token

AceKit can prompt for a token interactively on first run. For repeatable setup, export it before installing:

export ACEDATACLOUD_API_TOKEN=your_token

Do not commit real tokens to a repository. If you want teammates to reproduce the setup, document the variable name and let each developer provide their own value locally.

Step 2: Install the skill toolkit

Run the installer:

npx acekit

A documented run on a machine with Claude Code installed looks like this:

🃏  AceKit — wiring AI into your coding agent
✓  Detected: Claude Code
📦  Installing the AceData skill toolkit via @acedatacloud/skills …
Installed 19 skills to ~/.claude/skills
✅  Done. Try it now — ask your agent:
      "generate a hero image for this README"
      "turn this script into a 30-second video"

After installation, reload the agent so it can discover the new skills.

Step 3: Try a small synchronous task

Start with something deterministic, like shortening a URL. In plain language, you can ask the agent:

Use the short-url skill to shorten https://platform.acedata.cloud/services

Behind the scenes, the document shows the direct API shape:

curl -X POST https://api.acedata.cloud/shorturl \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content":"https://platform.acedata.cloud/services"}'

This is a useful smoke test because it is synchronous and quick. If the agent can call this skill and return a link, your token and skill installation are working.

Step 4: Add real-time search to agent work

Another simple but high-value test is search. The document gives this example call:

curl -X POST https://api.acedata.cloud/serp/google \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query":"OpenAI Sora release date","type":"search","number":3}'

In an agent workflow, the prompt can be more natural: ask it to search for a current API behavior, compare two libraries, or summarize recent documentation. The key improvement is that the agent can fetch fresh results instead of relying only on model memory.

Step 5: Understand asynchronous tools

Some capabilities are not instant. The document’s image example calls the Nano Banana image endpoint:

curl -X POST https://api.acedata.cloud/nano-banana/images \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"action":"generate","model":"nano-banana",
       "prompt":"a cute cartoon banana mascot waving hello, flat vector logo, white background"}'

The important lesson is not the mascot prompt. It is that the installed skill can handle the workflow around the API: building the request, authenticating, polling when needed, and returning the final image to the conversation.

That is where agent skills become more useful than a loose collection of curl snippets. They give the agent operational instructions, not just endpoint names.

Step 6: Know where skills are installed

The document lists these installation locations:

Claude Code                  ~/.claude/skills
Codex CLI                    ~/.agents/skills
Cursor / Gemini / OpenCode   ~/.agents/skills

If something does not appear in your agent, check the expected directory first, then restart the agent. For multi-agent setups, remember that some tools may read from ~/.agents/skills while Claude Code reads from ~/.claude/skills.

Optional: Claude Code environment settings

The document also shows that Ace Data Cloud can be used with Anthropic-compatible /v1/messages settings for Claude Code. The local project file is .claude/settings.local.json:

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

Keep this file local if it contains credentials.

Final notes

AceKit is most useful when your coding agent already understands the codebase but needs safe access to external capabilities: search, media generation, link tools, or model calls. Start with a small synchronous skill, verify the install path, then try longer-running tasks where polling matters.

The full setup details are in the AceKit Toolkit guide.

From One Sentence to a Product Photo: A Developer Guide to E-commerce Images with gpt-image-2

Germey — Mon, 20 Jul 2026 16:11:32 +0000

Product photography is one of those tasks that looks simple until you try to do it consistently.

A founder can write the copy, set up the checkout flow, and ship a small Shopify or Gumroad page in a weekend. But the moment the product page needs a clean hero image, everything slows down: camera, lighting, background, retouching, variants, and enough visual consistency that the store does not look like a collage of unrelated photos.

For indie makers and small e-commerce teams, that friction matters. A product image is often the first thing a buyer evaluates, but hiring a studio or building a mini studio is not always realistic during early validation.

That is where image generation can be useful: not as a replacement for every final catalog shot, but as a fast way to create polished product concepts, listing mockups, landing-page visuals, and ad creatives from plain English.

This post walks through a practical example using gpt-image-2: turning one sentence into a square e-commerce product photo through the Ace Data Cloud OpenAI image endpoint.

What is gpt-image-2?

gpt-image-2 is an image generation model that can create images from text prompts. For a developer workflow, the important part is not only that it can generate images, but that it can be called from an API with predictable parameters such as model, prompt, size, and output format.

That makes it useful when you need to build features like:

product-photo generation inside an admin dashboard
automatic visual variants for marketplace listings
placeholder imagery before a real shoot
creative testing for ads and landing pages
consistent product cards for a catalog prototype

The example below generates a clean product listing image: a matte black reusable stainless-steel water bottle on a neutral studio background.

Step 1: Write the product-photo prompt

For product imagery, avoid vague prompts like “make it beautiful.” You get better results when you specify the object, material, background, lighting, composition, and things to exclude.

Here is the exact prompt used for this example:

A realistic square e-commerce product photo of a matte black stainless steel water bottle centered on a light gray seamless studio background. Soft softbox lighting, gentle shadow, clean product listing style, no text, no logo, no props, sharp focus.

This prompt is intentionally plain English. It describes the result a photographer or designer would understand:

Subject: matte black stainless-steel water bottle
Composition: centered square product photo
Background: light gray seamless studio backdrop
Lighting: softbox lighting with a gentle shadow
Commercial constraints: no text, no logo, no extra props

The negative constraints matter. If you are making catalog images, random labels, decorative props, or hands holding the product can make the output harder to use.

Step 2: Call the API

The request is a normal HTTP POST to the image generation endpoint:

curl -X POST "https://api.acedata.cloud/openai/images/generations" \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A realistic square e-commerce product photo of a matte black stainless steel water bottle centered on a light gray seamless studio background. Soft softbox lighting, gentle shadow, clean product listing style, no text, no logo, no props, sharp focus.",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1,
    "output_format": "png",
    "response_format": "url",
    "background": "opaque"
  }'

The key fields are:

model: set this to gpt-image-2
prompt: the English product-photo description
size: 1024x1024, which works well for square product listings
n: number of images to generate
response_format: url, so the generated image can be embedded or downloaded
output_format: png, useful for product and UI assets

In a real application, you would usually store the returned image URL or copy the file into your own object storage. For a prototype, using the returned URL directly is often enough.

Step 3: Show the result

Here is the generated product image from the prompt above:

The output is not trying to be a lifestyle campaign image. It is a clean product-photo style asset: centered object, neutral background, soft shadow, and no distracting props. That is exactly the kind of image you can use while testing a product page layout or creating a first-pass catalog.

Step 4: Use it in a simple product workflow

A practical workflow for an indie maker might look like this:

Start with a short product description from your catalog.
Convert that description into a structured prompt.
Generate one to four square product images.
Pick the best image and place it into your storefront mockup.
Later, replace it with a real photo shoot if the product validates.

For example, if your database has this product record:

{
  "name": "Reusable Stainless Steel Bottle",
  "color": "matte black",
  "material": "brushed stainless steel",
  "style": "minimal outdoor lifestyle brand",
  "background": "light gray studio"
}

You can generate a prompt template like this:

A realistic square e-commerce product photo of a {color} {material} {name}, centered on a {background} seamless studio background. Softbox lighting, gentle shadow, clean product listing style, no text, no logo, no extra props, sharp focus.

That template is simple enough to maintain, but structured enough to produce consistent results across a small catalog.

Where this works well

This approach is especially useful before you have perfect assets.

If you are validating a product idea, you can generate listing images before ordering inventory. If you are building a marketplace, you can create placeholder visuals for empty categories. If you are designing a product-page builder, you can generate realistic demo content instead of relying on generic stock photos.

It also helps with creative exploration. You can test different backgrounds, lighting styles, or seasonal variants without setting up a new shoot each time. For example, you might try:

“on a warm beige studio background”
“with dramatic side lighting and a dark charcoal backdrop”
“minimal premium skincare product photography style”
“clean Amazon-style white background, no props”

The important part is to keep prompts operational. Describe the asset you want, the constraints it must satisfy, and how it will be used.

Where to be careful

Generated product images should be used responsibly. If the image represents a real SKU, make sure it does not mislead buyers about shape, texture, size, included accessories, or branding. For final product pages, you may still want real photography or carefully reviewed generated assets.

A good rule is: use generation to speed up concepting, layout design, and early testing; use human review before anything becomes a customer-facing claim.

Closing

For developers and indie makers, the value of gpt-image-2 is not magic. It is workflow compression. You can move from product description to usable visual asset with one API call, then iterate on the prompt until the image fits your store or prototype.

If you want to try the same workflow in a browser before wiring it into code, you can experiment with the image studio here: https://studio.acedata.cloud/openai-image

From One Sentence to a Product Photo: Generating E-commerce Images with gpt-image-2

Germey — Mon, 20 Jul 2026 16:10:54 +0000

Product photography is one of those tasks that looks simple until you try to do it consistently.

A founder can write the copy, set up the checkout flow, and ship a small Shopify or Gumroad page in a weekend. But the moment the product page needs a clean hero image, everything slows down: you need a camera, lighting, a neutral background, retouching, variants for different angles, and enough consistency that the store does not look like a collage of unrelated photos.

For indie makers and small e-commerce teams, that friction matters. A product image is often the first thing a buyer evaluates, but hiring a studio or setting up a mini studio is not always realistic during the early validation phase.

In this post, I will walk through a practical example using gpt-image-2: turning one sentence into a square e-commerce product photo through the Ace Data Cloud OpenAI image endpoint.

What is gpt-image-2?

That makes it useful when you need to build features like:

product-photo generation inside an admin dashboard
automatic visual variants for marketplace listings
placeholder imagery before a real shoot
creative testing for ads and landing pages
consistent product cards for a catalog prototype

The example below generates a clean product listing image: a matte black reusable stainless-steel water bottle on a neutral studio background.

Step 1: Write the product-photo prompt

For product imagery, I usually avoid vague prompts like “make it beautiful.” You get better results when you specify the object, material, background, lighting, composition, and things to exclude.

Here is the exact prompt used for this example:

A realistic square e-commerce product photo of a matte black stainless steel water bottle centered on a light gray seamless studio background. Soft softbox lighting, gentle shadow, clean product listing style, no text, no logo, no props, sharp focus.

This prompt is intentionally plain English. It describes the result a photographer or designer would understand:

Subject: matte black stainless-steel water bottle
Composition: centered square product photo
Background: light gray seamless studio backdrop
Lighting: softbox lighting with a gentle shadow
Commercial constraints: no text, no logo, no extra props

The negative constraints matter. If you are making catalog images, random labels, decorative props, or hands holding the product can make the output harder to use.

Step 2: Call the API

The request is a normal HTTP POST to the image generation endpoint:

curl -X POST "https://api.acedata.cloud/openai/images/generations" \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A realistic square e-commerce product photo of a matte black stainless steel water bottle centered on a light gray seamless studio background. Soft softbox lighting, gentle shadow, clean product listing style, no text, no logo, no props, sharp focus.",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1,
    "output_format": "png",
    "response_format": "url",
    "background": "opaque"
  }'

The key fields are:

model: set this to gpt-image-2
prompt: the English product-photo description
size: 1024x1024, which works well for square product listings
n: number of images to generate
response_format: url, so the generated image can be embedded or downloaded
output_format: png, useful for product and UI assets

In a real application, you would usually store the returned image URL or copy the file into your own object storage. For a prototype, using the returned URL directly is often enough.

Step 3: Show the result

Here is the generated product image from the prompt above:

Step 4: Use it in a simple product workflow

A practical workflow for an indie maker might look like this:

Start with a short product description from your catalog.
Convert that description into a structured prompt.
Generate one to four square product images.
Pick the best image and place it into your storefront mockup.
Later, replace it with a real photo shoot if the product validates.

For example, if your database has this product record:

{
  "name": "Reusable Stainless Steel Bottle",
  "color": "matte black",
  "material": "brushed stainless steel",
  "style": "minimal outdoor lifestyle brand",
  "background": "light gray studio"
}

You can generate a prompt template like this:

A realistic square e-commerce product photo of a {color} {material} {name}, centered on a {background} seamless studio background. Softbox lighting, gentle shadow, clean product listing style, no text, no logo, no extra props, sharp focus.

That template is simple enough to maintain, but structured enough to produce consistent results across a small catalog.

Where this works well

This approach is especially useful before you have perfect assets.

It also helps with creative exploration. You can test different backgrounds, lighting styles, or seasonal variants without setting up a new shoot each time. For example, you might try:

“on a warm beige studio background”
“with dramatic side lighting and a dark charcoal backdrop”
“minimal premium skincare product photography style”
“clean Amazon-style white background, no props”

The important part is to keep prompts operational. Describe the asset you want, the constraints it must satisfy, and how it will be used.

Where to be careful

A good rule is: use generation to speed up concepting, layout design, and early testing; use human review before anything becomes a customer-facing claim.

Closing

If you want to try the same workflow in a browser before wiring it into code, you can experiment with the image studio here: https://studio.acedata.cloud/openai-image

How to Add Generate and Edit Image Workflows with the Nano Banana Images API

Germey — Mon, 20 Jul 2026 01:07:31 +0000

A lot of image features start simple: generate one picture from a prompt, or edit an existing image from a product page. The hard part is turning that into a backend workflow that is predictable enough for an app.

This guide shows how to wire a small generate-and-edit pipeline with the Ace Data Cloud Nano Banana Images API. We will keep it practical: one endpoint, the real request fields, a curl example, a Python wrapper, and a few notes that matter when you move from playground experiments to application code.

What you can do

The Nano Banana Images API supports two actions through the same endpoint:

generate: create images from a text prompt
edit: edit one or more input images with a prompt

The documented interface is:

Base URL: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Auth header: authorization: Bearer {token}
Request headers: accept: application/json and content-type: application/json
Optional callback_url for asynchronous completion notifications
Optional count from 1 to 4, defaulting to 1

The model field is optional. The documented choices include nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, plus corresponding :official variants such as nano-banana-pro:official.

For app developers, the useful part is that generation and editing share the same response idea: a successful call returns success, a task_id, a trace_id, and a data[] list containing image results.

How it works

For generation, the minimum required fields are action and prompt. You can add model when you want a specific model, and count when you want more than one result.

Here is the documented cURL pattern:

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": "generate",
    "model": "nano-banana-pro",
    "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "count": 1
  }'

A successful response looks like this:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist...",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

In a production backend, image_url is the field you usually persist. task_id is useful for correlating the request with your own job record, and trace_id is useful when debugging failures.

Generate: keep prompts specific and save the result URL

A generation request is straightforward, but prompt quality still matters. I prefer to store prompts as structured templates instead of raw text scattered through the codebase. For example, a product image workflow could build the prompt from fields like subject, style, lighting, and orientation.

Here is a compact Python wrapper:

import requests

API_URL = "https://api.acedata.cloud/nano-banana/images"

def generate_image(token: str, prompt: str, model: str = "nano-banana-pro", count: int = 1):
    headers = {
        "authorization": f"Bearer {token}",
        "accept": "application/json",
        "content-type": "application/json",
    }
    payload = {
        "action": "generate",
        "model": model,
        "prompt": prompt,
        "count": count,
    }
    response = requests.post(API_URL, json=payload, headers=headers, timeout=120)
    response.raise_for_status()
    result = response.json()
    return [item["image_url"] for item in result.get("data", [])]

The API supports count from 1 to 4. The document notes that if some images fail, only successful images are returned and billed. That means your code should treat data as a list that may contain fewer items than requested.

Edit: pass one or more source images with `image_urls`

For editing, set action to edit, provide a prompt, and pass source images through image_urls. The document says these can be publicly accessible http or https URLs, or base64-encoded images such as a data:image/png;base64,... string.

A documented edit request looks like this:

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",
    "prompt": "let this man wear on this T-shirt",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

That pattern is useful for common app features: virtual try-on experiments, combining a product image with a scene, changing an object style, or applying a brand asset to a generated background. The key is to make the relationship between the images explicit in the prompt.

Add callbacks when the UI should not wait

The API supports an optional callback_url so your service can receive task completion notifications and results asynchronously. This is usually a better fit for web apps than keeping a browser request open.

A simple architecture is:

Your frontend submits a generation or edit job to your backend.
Your backend calls POST /nano-banana/images with callback_url.
You store task_id and initial status in your database.
When the callback arrives, you save the returned image_url values and notify the user interface.

Even if you start synchronously, design your database around jobs rather than one-off responses. Image workflows often become queues later.

Handle errors as first-class data

The documented error response includes an error object and a trace_id. Do not throw that information away. Log the trace ID with your internal request ID so you can debug problems later.

For example, wrap your request like this:

try:
    urls = generate_image(token, prompt)
except requests.HTTPError as exc:
    body = exc.response.text if exc.response is not None else ""
    raise RuntimeError(f"Nano Banana request failed: {body}") from exc

In a real system, you would parse the JSON body and store error.code, error.message, and trace_id in your job table.

Closing notes

The nice thing about this API shape is that it keeps the workflow small: one endpoint, an action switch, a prompt, optional source images, and a result list of image URLs. Start with generate for prompt-only features, move to edit when you need source images, and add callback_url once the user experience needs background jobs.

The full Ace Data Cloud document has the complete examples and parameter notes: Nano Banana Images API Integration Guide.