Tutorial · Developer Tutorials

Ecommerce Image AI: Run Commerce AI Text and Image Jobs Locally

Run the open-source ecommerce-image-ai demo: discover the AI billing shop, estimate Credits, execute text.translate or image jobs, and poll until settlement — without mixing Product API units.

HHioBuy Developer Team•8 min read•

Ecommerce Image AI: open-source Commerce AI text and image jobs

Ecommerce Image AI: Run Commerce AI Text and Image Jobs Locally

China catalog images often arrive with Chinese overlay text, busy backgrounds, and titles that still need localization. Before you wire that into a storefront or importer, you need a small loop that can estimate AI Credits, run one of the four public Commerce AI V1 operations, and poll the job until it settles.

hiobuy/ecommerce-image-ai is an open-source (MIT) developer demo for exactly that. A Vite page talks to a local Node server on 127.0.0.1:8790. The App API key never leaves the server. Automated tests use mocks; they do not prove a live HioBuy account accepted a request.

There is no hosted public demo. You run npm run dev and open http://127.0.0.1:5173.

This tutorial covers:

  1. When to call which Commerce AI operation.
  2. Local setup, shop discovery, and env vars.
  3. Credits: pricing rules, estimate vs charge, and why they are not Product API units.
  4. Image URL constraints and job polling.
  5. Common errors and safe retries.

What this demo is (and is not)

It is a local developer playground for the four public V1 capabilities. It does not sign people in, take payment, or sell credits. It does not expose an open URL proxy. The browser only calls /api/* on the local server; Authorization is added in server/.

What it exercises:

CapabilityFeature keyRequestStandard published unit
Text translationtext.translatePOST /v1/ai/text/translate2 Credits / 1,000 UTF-16
Remove Chinese textimage.remove_chinese_textPOST /v1/ai/image/jobs · remove_chinese_text1 Credit / image
Translate image textimage.replace_chinese_textPOST /v1/ai/image/jobs · replace_chinese_text2 Credits / image
White backgroundimage.backgroundPOST /v1/ai/image/jobs · white_background1 Credit / image

Source: Commerce AI V1. Effective App prices come from GET /v1/ai/credits/pricing (rules[].credits when rules[].enabled is true). Do not use default_credits as the price. Private operations such as image.lifestyle are not included.

What it is not:

  • A white-label storefront or C-end shopping blog.
  • A product search/order/fulfillment integration (those are separate Product / Fulfillment APIs).
  • A public image upload API — you must host image_url yourself on a Gateway-approved HTTPS host.

When to use which operation

Need localized title / description / attributes?
  → POST /v1/ai/text/translate
     scene: e-commerce-title | e-commerce-description | e-commerce-chat | e-commerce-cpv
     format_type: text | html

Need a catalog photo without Chinese overlay?
  → POST /v1/ai/image/jobs  type=remove_chinese_text

Need the same photo with translated on-image text?
  → POST /v1/ai/image/jobs  type=replace_chinese_text  + target_language

Need a clean white-canvas product shot?
  → POST /v1/ai/image/jobs  type=white_background
     (pricing feature key: image.background)

Text accepts 1–50 non-empty strings. Trimmed total must be at most 50,000 UTF-16 units. The demo page sends the textarea as one string. Source language defaults to auto on the API; the README curl examples often set zh → en explicitly.

Image jobs are one image per job. Creation returns HTTP 200 (idempotent replay) or 202 (new recorded job). Neither code alone means success — inspect job.status, job.billing_state, and job.error.

Discover account, read pricing, estimate, execute, then poll

Safe call order

1. GET  /v1/ai/account                 # no X-Shop-Domain — save shop
2. GET  /v1/ai/credits/pricing         # rules[].credits + enabled
3. GET  /v1/ai/credits                 # credits_balance (with X-Shop-Domain)
4. POST /v1/ai/credits/estimate        # no reservation, no model call
5. POST /v1/ai/text/translate
   or POST /v1/ai/image/jobs           # X-Idempotency-Key per intent
6. GET  /v1/ai/jobs/{job_id}           # until completed | failed | refunded
7. GET  /v1/ai/credits                 # refreshed balance after settlement

Persist one X-Idempotency-Key per processing intent. Network retries reuse the same key, body, and billing account. A deliberate new operation needs a new key and can charge again. If the API returns 409 AI_REQUEST_IN_PROGRESS or AI_RECONCILIATION_REQUIRED, poll details.job_id — do not create a replacement paid task for the same outcome.

Prerequisites

  • Node.js 20+ and npm.
  • A HioBuy App API key with Commerce AI access enabled. A Product API subscription alone does not enable AI.
  • Prepaid AI calls need the product:translate scope. Test keys are rejected by live AI (AI_TEST_KEY_NOT_ALLOWED).
  • The prepaid AI account shop for that same key (billing identifier — not an App ID, Workspace ID, or a domain you invent).

AI Credits are independent of Product API daily units. Product trial units (for example Trial 100/day, Starter $59 / 1,000/day, Growth $99 / 8,000/day, Enterprise $299 / 50,000/day) do not fund AI jobs. Do not conflate the two quotas.

Step 1: Clone and configure

git clone https://github.com/hiobuy/ecommerce-image-ai.git
cd ecommerce-image-ai
npm install
cp .env.example .env

Edit .env (server-side only):

HIOBUY_API_KEY=
HIOBUY_AI_SHOP=
HIOBUY_API_BASE_URL=https://api.hiobuy.com
PORT=8790

Do not paste the key into frontend code, tickets, or screenshots. Do not commit .env.

Step 2: Discover the AI billing shop

Call account discovery with the App key and no X-Shop-Domain header:

curl --fail --silent 'https://api.hiobuy.com/v1/ai/account' \
  --header "Authorization: Bearer $HIOBUY_API_KEY"

Copy the returned shop into HIOBUY_AI_SHOP. You can also copy the same value from that App’s HTTP example in Developer Center. If the call returns 404 AI_ACCOUNT_NOT_FOUND, create the prepaid account under Developer Center → AI Enhancement.

On startup, and before any shop-scoped call, this demo compares HIOBUY_AI_SHOP with GET /v1/ai/account. If they differ, it stops (DEMO_ACCOUNT_MISMATCH). A different shop selects a different account.

Illustrative discovery response (always use the value returned for your key):

{
  "request_id": "req_example",
  "workspace_id": "aiw_example",
  "shop": "app-0123456789abcdef01234567.ai.hiobuy.invalid",
  "account_type": "prepaid",
  "status": "active",
  "currency": "USD",
  "credits_balance": 0
}

A zero balance still returns HTTP 200 on discovery. Paid operations still require sufficient Credits.

Step 3: Run locally

npm run dev

Open http://127.0.0.1:5173. The Vite page proxies /api to http://127.0.0.1:8790. The API process listens on localhost only.

Production-style check on one port:

npm run build
npm start

npm start serves the built page and the API on port 8790. Also available: npm run typecheck, npm test.

Step 4: Credits — pricing, estimate, charge

The page shows:

  • credits_balance from GET /v1/ai/credits
  • the selected feature’s rules[].credits when rules[].enabled is true
  • credits_required from POST /v1/ai/credits/estimate
  • credits_used after the operation, then a fresh balance read

Estimate does not reserve Credits and does not guarantee the later charge. The demo does not invent a local balance by subtracting, and it does not sell credits.

New developers may receive 100 free AI Credits, subject to current eligibility. That is not a promise that every account has 100 Credits. Product API trial units are a different quota. Published purchase reference on the Commerce AI page: 1 USD = 100 Credits for listed top-up offers in Developer Center; available offers and gates are server-authoritative. This tutorial does not invent additional AI credit prices.

Text billing is ceil(total_utf16 / 1000) × effective unit price, rounded once over the batch. At the V1 standard price: 1–1,000 units = 2 Credits; 1,001–2,000 = 4; and so on. Confirm live with estimate + pricing.

Example text estimate body (same shape as execution):

POST /v1/ai/credits/estimate
Authorization: Bearer YOUR_APP_API_KEY
X-Shop-Domain: SHOP_RETURNED_BY_AI_ACCOUNT
Content-Type: application/json

{
  "feature": "text.translate",
  "texts": ["纯棉短袖T恤", "白色"],
  "target_language": "en",
  "format_type": "text",
  "scene": "e-commerce-title"
}

Example image estimate:

{
  "feature": "image.remove_chinese_text",
  "count": 1
}

Step 5: Execute text or an image job

Text (server-side; key never in the browser):

curl --request POST "$HIOBUY_API_BASE_URL/v1/ai/text/translate" \
  --header "Authorization: Bearer YOUR_APP_API_KEY" \
  --header "X-Shop-Domain: $HIOBUY_AI_SHOP" \
  --header "X-Idempotency-Key: text-translation-001" \
  --header "Content-Type: application/json" \
  --data '{"texts":["纯棉短袖T恤"],"source_language":"zh","target_language":"en","format_type":"text","scene":"e-commerce-title"}'

Remove Chinese text on an image:

curl --request POST "$HIOBUY_API_BASE_URL/v1/ai/image/jobs" \
  --header "Authorization: Bearer YOUR_APP_API_KEY" \
  --header "X-Shop-Domain: $HIOBUY_AI_SHOP" \
  --header "X-Idempotency-Key: remove-image-001" \
  --header "Content-Type: application/json" \
  --data '{"type":"remove_chinese_text","image_url":"https://cdn.example.com/product.jpg"}'

replace_chinese_text also sends target_language. white_background does not. Replace the example CDN URL with an approved host before execution.

Image URL requirements

image_url must be HTTPS on a host the Gateway allows. The API rejects local files, base64, multipart uploads, and arbitrary public domains. A URL that opens in a browser can still be rejected (IMAGE_HOST_NOT_ALLOWED / UNSAFE_IMAGE_URL).

This demo does not upload files and does not add storage. Host the image yourself on an approved CDN, or ask HioBuy to review the host. The signed-in Developer Center playground upload is not a public API.

Default download limits published with the API: 10 MiB, 25,000,000 pixels, 3 redirects, 15 seconds. Deployment settings can differ.

After completion, read job.output.url and re-host results before saving permanent catalog URLs. Anyone with the processed asset URL can read it. Prefer that field over inventing paths; GET /v1/ai/assets/{job_id}.webp exists as a public WebP route, but normal clients use job.output.url.

Step 6: Poll until terminal

curl 'https://api.hiobuy.com/v1/ai/jobs/YOUR_JOB_ID' \
  --header "Authorization: Bearer $HIOBUY_API_KEY" \
  --header "X-Shop-Domain: $HIOBUY_AI_SHOP"
FieldMeaning
job.statusqueued, running, completed, failed, or refunded
job.output.urlImage result URL after completion
job.credits_reservedHeld Credits (not an extra fee on top of settlement)
job.credits_usedFinal settled consumption (may be 0 while still running)
job.billing_stateIncludes reserved, executing, provider_succeeded, completed, refunded, reconciliation

provider_succeeded or reconciliation can still show job.status as running. Keep polling that job. The job query does not refresh balance — call GET /v1/ai/credits after settlement.

Refreshing status reads the same job. “Run again” in the demo creates a new idempotency key and can charge again.

Public V1 tasks have at most 3 execution attempts and a 10-minute window from creation. Terminal failures return failed + billing_state=refunded + credits_used=0 with codes such as AI_JOB_TIMEOUT, AI_RETRY_EXHAUSTED, or AI_PROVIDER_OUTCOME_UNKNOWN. Reserved Credits are returned once.

Rate limits (high level)

Defaults published for Commerce AI (App-shared; overrides can apply): about 60 task-create requests/minute, 1,200 job polls/minute, and 300 metadata requests/minute in separate buckets. Up to 5 image jobs and 10 total jobs may be queued/running per App. Text jobs do not consume the image sub-limit but share the total. Prepaid protection can also share a developer-level in-flight image limit after top-up. Read error.code, error.details, and Retry-After / retry_after_seconds. Source: Commerce AI V1.

Common errors

What you seeWhat to check
Setup needed / DEMO_NOT_CONFIGURED.env has both HIOBUY_API_KEY and HIOBUY_AI_SHOP. Restart npm run dev.
DEMO_ACCOUNT_MISMATCHHIOBUY_AI_SHOP is not the shop from GET /v1/ai/account.
401Missing, revoked, or non-Bearer API key.
402Not enough Credits. Top up in Developer Center if you want to continue.
403AI access, product:translate, or the feature is not enabled. Test keys cannot call live AI.
400 IMAGE_HOST_NOT_ALLOWED / UNSAFE_IMAGE_URLUse an approved HTTPS image host.
409 AI_REQUEST_IN_PROGRESS / AI_RECONCILIATION_REQUIREDPoll details.job_id. Do not start another paid task for the same outcome.
429Wait for Retry-After. Creation, polling, and metadata have separate limits. Codes can include AI_PREPAID_SAFETY_LIMIT, RATE_LIMIT_EXCEEDED, AI_RATE_LIMIT_EXCEEDED.
503If nothing was accepted, retry the same idempotency key and body. If a job id exists, poll that job.

Contact support@hiobuy.com with the request_id. Do not send the API key.

Architecture worth copying

  • Key stays on the server. Browser → /api/* → local Node → https://api.hiobuy.com.
  • Shop discovery is automatic. Configure only the key; fetch shop from /v1/ai/account and bind it to that credential.
  • Estimate before execute. Gate on affordability, then persist idempotency keys.
  • Poll, don’t recreate. In-progress / reconciliation is not a signal to create a second paid job.
  • Allow-list image hosts. Reject base64 and local files at the edge of your own API.

Stack from the repo: Node ≥ 20, npm workspaces (client + server), TypeScript, Vite on 5173, API on 8790, MIT license.

Next steps

  1. Clone hiobuy/ecommerce-image-ai, set .env, run npm run dev.
  2. Discover shop, estimate a title translation, then execute once and confirm Credits moved.
  3. Point an approved HTTPS product image at remove_chinese_text or white_background, poll to completed, and re-host job.output.url.
  4. When you need catalog search + Shopify import around the same AI ops, see the related open-source shopify-1688-importer tutorial — Product API units and AI Credits remain separate.

API reference: Commerce AI V1 · Public API index.


Next step

If you already understand the workflow, move to the API reference for exact request and response fields, or open the developer console to create your application.

Ready to build?

Open the API documentation or create your HioBuy developer application.

Related guides