alexa-ai 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `alexa-ai` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [2.3.0] — 2026-09-07
+
+### Added
+- **Multiple `/api/*` transports** (`transport` option / `DEEPAI_TRANSPORT`):
+  `'auto'` (default) tries `fetch`, then system `curl`, then a
+  `curl-impersonate` binary (Chrome TLS profile) when one is available;
+  `'fetch' | 'curl' | 'impersonate'` pin a single transport. A refusal of the
+  form "Please try this model on deepai.org" can be specific to the client
+  TLS stack, so `auto` retries that error through the next transport — quota
+  and auth errors are never re-driven. `curlImpersonatePath` /
+  `DEEPAI_CURL_IMPERSONATE` locate the binary.
+- `examples/diagnose.js` — runs the browser-shaped request through every
+  transport with fresh keys and reports which one the network accepts.
+- `examples/text2img-standalone.js` gained `--transport fetch|curl|impersonate`
+  and `--imp <path>`.
+
 ## [2.2.1] — 2026-09-07
 
 ### Added

package/README.md

@@ -872,7 +872,27 @@ separate requirements:
    cookie value) also helps the per-device quota.
 
 `examples/text2img-standalone.js` is a zero-dependency CLI implementing the
-full recipe.
+full recipe, and `examples/diagnose.js` runs the same request through every
+transport on your machine and prints which one DeepAI accepts.
+
+**`transport` option (2.3.0).** Some networks serve non-browser TLS stacks a
+refusal (`"Please try this model on deepai.org"`) even with a perfectly valid
+key. `/api/*` calls therefore support multiple transports:
+
+```js
+new AlexaAI({ key, postgresUrl, transport: 'auto' })   // default: fetch → curl → curl-impersonate
+new AlexaAI({ key, postgresUrl, transport: 'curl' })   // system curl only
+new AlexaAI({ key, postgresUrl, transport: 'impersonate', curlImpersonatePath: 'C:/tools/curl-impersonate.exe' })
+```
+
+With `transport: 'auto'` (the default) the engine starts with `fetch` and, on
+a transport-specific refusal, retries the request through system `curl`
+(shipped with Windows 10+, macOS and Linux) and then through a
+`curl-impersonate` binary if one is on PATH (a Chrome TLS profile; set
+`curlImpersonatePath` or `DEEPAI_CURL_IMPERSONATE` to point at it — builds:
+github.com/lexiforest/curl-impersonate/releases). Quota and auth errors are
+never re-driven through other transports. Run `node examples/diagnose.js` to
+see which transport your network accepts.
 
 **`generateImage()` returns `{ ok: false, error: 'DEEPAI_QUOTA_EXCEEDED' }`**
 `/api/text2img` is Pro-only for registered keys ("APIs are only available for

package/examples/diagnose.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * diagnose.js — DeepAI text2img connectivity diagnostic.
+ *
+ * Run ON THE MACHINE where the browser playground works:
+ *
+ *   node examples/diagnose.js
+ *   node examples/diagnose.js --device-id <your deepai_device_id cookie>
+ *   node examples/diagnose.js --imp /path/to/curl-impersonate
+ *
+ * Each test sends the browser-shaped request with a FRESH single-use key
+ * through a different transport and prints the raw server response, so one
+ * run shows exactly which transport DeepAI accepts on your network:
+ *
+ *   1. Node fetch   (the library default)
+ *   2. system curl
+ *   3. curl-impersonate with a Chrome TLS profile (if the binary is found)
+ *
+ * Zero dependencies, Node 18+.
+ */
+
+const API = 'https://api.deepai.org/api/text2img';
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36';
+const PROFILE_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
+const SALT = 'hackers_become_a_little_stinkier_every_time_they_hack';
+
+// ---- key hash (same algorithm as DeepAIClient._islandHash) ----------------
+function islandHash(input) {
+    const a = [];
+    for (let b = 0; 64 > b; ) a[b] = 0 | (4294967296 * Math.sin(++b % Math.PI));
+    let d, e, f, g = [(d = 1732584193), (e = 4023233417), ~d, ~e], h = [];
+    const l = unescape(encodeURI(input)) + '\u0080';
+    let k = l.length;
+    let c = (--k / 4 + 2) | 15;
+    for (h[--c] = 8 * k; ~k; ) h[k >> 2] |= l.charCodeAt(k) << (8 * k--);
+    for (let b = 0, m = 0; b < c; b += 16) {
+        for (k = g; 64 > m; k = [ (f = k[3]), d + (((f = k[0] + [d & e | ~d & f, f & d | ~f & e, d ^ e ^ f, e ^ (d | ~f)][(k = m >> 4)] + a[m] + ~~h[b | [m, 5 * m + 1, 3 * m + 5, 7 * m][k] & 15]) << (k = [7, 12, 17, 22, 5, 9, 14, 20, 4, 11, 16, 23, 6, 10, 15, 21][4 * k + (m++ % 4)])) | (f >>> -k)), d, e ]) {
+            d = k[1] | 0;
+            e = k[2];
+        }
+        for (m = 4; m; ) g[--m] += k[m];
+    }
+    let result = '';
+    for (let i = 0; 32 > i; ) result += ((g[i >> 3] >> 4 * (1 ^ i++)) & 15).toString(16);
+    return result.split('').reverse().join('');
+}
+const freshKey = (ua) => {
+    const digits = String(Math.round(Math.random() * 100000000000));
+    return `tryit-${digits}-${islandHash(ua + islandHash(ua + islandHash(ua + digits + SALT)))}`;
+};
+
+// ---- args -------------------------------------------------------------------
+const args = process.argv.slice(2);
+const opt = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--device-id') opt.deviceId = args[++i];
+    else if (args[i] === '--imp') opt.imp = args[++i];
+}
+const deviceId = opt.deviceId || Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64url');
+const cookie = `deepai_device_id=${deviceId}`;
+
+// ---- transports ---------------------------------------------------------------
+async function viaFetch() {
+    const form = new FormData();
+    form.append('text', 'a small red boat on a calm lake');
+    form.append('generation_source', 'img');
+    const res = await fetch(API, {
+        method: 'POST', body: form,
+        headers: { 'api-key': freshKey(UA), 'User-Agent': UA, Origin: 'https://deepai.org', Referer: 'https://deepai.org/machine-learning-model/text2img', Accept: '*/*', Cookie: cookie },
+    });
+    return { status: res.status, body: await res.text() };
+}
+
+function runCurl(binary, impersonate) {
+    const { execFileSync } = require('child_process');
+    const ua = impersonate ? PROFILE_UA : UA;
+    const a = impersonate ? ['--impersonate', 'chrome136'] : [];
+    a.push(API, '-sS', '--compressed', '--max-time', '60', '-X', 'POST',
+        '-H', `api-key: ${freshKey(ua)}`);
+    if (!impersonate) a.push('-H', `User-Agent: ${ua}`);
+    a.push('-H', 'Origin: https://deepai.org',
+        '-H', 'Referer: https://deepai.org/machine-learning-model/text2img',
+        '-H', 'Accept: */*',
+        '-H', `Cookie: ${cookie}`,
+        '-F', 'text=a small red boat on a calm lake',
+        '-F', 'generation_source=img',
+        '-w', '\n%{http_code}');
+    const out = execFileSync(binary, a, { encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] }).replace(/\r/g, '');
+    const cut = out.lastIndexOf('\n');
+    return { status: Number(out.slice(cut + 1).trim()), body: out.slice(0, cut) };
+}
+
+function label(t) {
+    const b = String(t.body).slice(0, 140).replace(/\s+/g, ' ');
+    if (t.status === 200 && /share_url|output_url/.test(t.body)) return `✅ SUCCESS — image generated (HTTP 200)`;
+    if (/valid Api-Key/i.test(b)) return `❌ key rejected (unexpected — fresh key was used)`;
+    if (/try this model/i.test(b)) return `❌ transport refused ("Please try this model on deepai.org")`;
+    if (/Pro members/i.test(b)) return `❌ account-level refusal (needs a Pro key)`;
+    if (/try it exceeded/i.test(b)) return `⚠️ free quota exhausted for this device/IP — retry later or change --device-id`;
+    return `❌ HTTP ${t.status}: ${b}`;
+}
+
+(async () => {
+    console.log(`DeepAI text2img diagnostic — device ${deviceId.slice(0, 8)}…\n`);
+    const rows = [];
+    try { rows.push(['1. Node fetch (library default)', label(await viaFetch())]); } catch (e) { rows.push(['1. Node fetch', `⚠️ ${e.message}`]); }
+    try { rows.push(['2. system curl', label(runCurl('curl', false))]); } catch (e) { rows.push(['2. system curl', `⚠️ ${e.message.split('\n')[0]}`]); }
+
+    let impBin = opt.imp;
+    if (!impBin) {
+        const { execFileSync } = require('child_process');
+        for (const name of ['curl-impersonate', 'curl-impersonate.exe']) {
+            try { execFileSync(name, ['--version'], { timeout: 5000, stdio: 'ignore' }); impBin = name; break; } catch { /* keep looking */ }
+        }
+    }
+    if (impBin) {
+        try { rows.push([`3. curl-impersonate (${impBin})`, label(runCurl(impBin, true))]); } catch (e) { rows.push(['3. curl-impersonate', `⚠️ ${e.message.split('\n')[0]}`]); }
+    } else {
+        rows.push(['3. curl-impersonate', '⏭ skipped — binary not found (see README for install)']);
+    }
+
+    for (const [name, v] of rows) console.log(`${name.padEnd(34)} ${v}`);
+    console.log(`
+Reading the results:
+- A ✅ on ANY line    → that transport works; use it (library: transport option,
+                        standalone: --transport).
+- ❌ on line 1 only   → non-browser TLS stack refused; use 'curl' or
+                        'impersonate'.
+- ❌ on lines 1+2, ✅ on 3 → strict browser-TLS matching; use 'impersonate'.
+- ❌ everywhere      → the IP is refused for anonymous generation, or the free
+                        quota is exhausted. Compare with the browser: DevTools
+                        → Network → generate → text2img request → Response.`);
+})();

package/examples/text2img-standalone.js

@@ -13,9 +13,16 @@
  *   node examples/text2img-standalone.js "a cat" --aspect 16:9
  *   node examples/text2img-standalone.js "a cat" --device-id <cookieValue>
  *   node examples/text2img-standalone.js "a cat" --key <proKey>
+ *   node examples/text2img-standalone.js "a cat" --transport curl
+ *   node examples/text2img-standalone.js "a cat" --transport impersonate --imp /path/to/curl-impersonate
  *
- * Requires Node.js 18+ (global fetch). Anonymous generation is refused
- * from datacenter/VPN IPs; run from a residential network.
+ * Transports: 'fetch' (default, Node fetch) | 'curl' (system curl) |
+ * 'impersonate' (curl-impersonate binary, Chrome TLS profile). Some
+ * networks serve non-browser TLS stacks a refusal — if 'fetch' fails with
+ * "Please try this model on deepai.org", try 'curl', then 'impersonate'.
+ *
+ * Requires Node.js 18+. Anonymous generation is refused from
+ * datacenter/VPN IPs; run from a residential network.
  */
 
 const API_URL = 'https://api.deepai.org/api/text2img';
@@ -65,7 +72,7 @@ function randomDeviceId() {
 // CLI
 // ---------------------------------------------------------------------------
 function parseArgs(argv) {
-    const opts = { prompt: '', out: null, key: null, deviceId: randomDeviceId(), aspect: null, genSource: 'img' };
+    const opts = { prompt: '', out: null, key: null, deviceId: randomDeviceId(), aspect: null, genSource: 'img', transport: 'fetch', imp: null };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--out') opts.out = argv[++i];
@@ -73,6 +80,8 @@ function parseArgs(argv) {
         else if (a === '--device-id') opts.deviceId = argv[++i];
         else if (a === '--aspect') opts.aspect = argv[++i];
         else if (a === '--chat-source') opts.genSource = 'chat';
+        else if (a === '--transport') opts.transport = argv[++i];
+        else if (a === '--imp') opts.imp = argv[++i];
         else if (a === '--help' || a === '-h') opts.help = true;
         else if (!opts.prompt) opts.prompt = a;
     }
@@ -84,7 +93,7 @@ const ASPECTS = { '16:9': [832, 448], '4:3': [768, 576], '1:1': [640, 640], '3:4
 async function main() {
     const opts = parseArgs(process.argv.slice(2));
     if (opts.help || !opts.prompt) {
-        console.log('Usage: node examples/text2img-standalone.js "your prompt" [--out file.jpg] [--key PRO_KEY] [--device-id VALUE] [--aspect 16:9|1:1|9:16|4:3|3:4] [--chat-source]');
+        console.log('Usage: node examples/text2img-standalone.js "your prompt" [--out file.jpg] [--key PRO_KEY] [--device-id VALUE] [--aspect 16:9|1:1|9:16|4:3|3:4] [--chat-source] [--transport fetch|curl|impersonate] [--imp PATH]');
         process.exit(opts.help ? 0 : 1);
     }
 
@@ -119,7 +128,39 @@ async function main() {
     console.log(`Key    : ${opts.key ? '(registered key — needs Pro)' : apiKey + '  (fresh, single-use)'}`);
     console.log('POST   : ' + API_URL);
 
-    const res = await fetch(API_URL, { method: 'POST', headers, body: form });
+    let res;
+    if (opts.transport === 'curl' || opts.transport === 'impersonate') {
+        const { execFile } = require('child_process');
+        const binary = opts.transport === 'impersonate' ? (opts.imp || 'curl-impersonate') : 'curl';
+        // the chrome136 profile sends its own Mac Chrome UA — the anonymous
+        // key hash must be derived from exactly that UA
+        const profileUa = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
+        const apiKey = opts.key || freshTryItKey(opts.transport === 'impersonate' ? profileUa : USER_AGENT);
+        const curlArgs = [];
+        if (opts.transport === 'impersonate') curlArgs.push('--impersonate', 'chrome136');
+        curlArgs.push(API_URL, '-sS', '--compressed', '--max-time', '120', '-X', 'POST',
+            '-H', `api-key: ${apiKey}`);
+        if (opts.transport !== 'impersonate') curlArgs.push('-H', `User-Agent: ${USER_AGENT}`);
+        curlArgs.push(
+            '-H', `Origin: ${headers.Origin}`,
+            '-H', `Referer: ${headers.Referer}`,
+            '-H', 'Accept: */*',
+            '-H', `Cookie: deepai_device_id=${opts.deviceId}`,
+            '-w', '\n%{http_code}'
+        );
+        for (const [k, v] of form.entries()) curlArgs.push('-F', `${k}=${v}`);
+        res = await new Promise((resolve, reject) => {
+            execFile(binary, curlArgs, { timeout: 120000, maxBuffer: 32 * 1024 * 1024 }, (err, stdout) => {
+                if (err && stdout == null) return reject(err);
+                const body = String(stdout).replace(/\r/g, '');
+                const cut = body.lastIndexOf('\n');
+                const status = Number(body.slice(cut + 1).trim());
+                resolve({ status, ok: status < 300, text: async () => body.slice(0, cut) });
+            });
+        });
+    } else {
+        res = await fetch(API_URL, { method: 'POST', headers, body: form });
+    }
     const raw = await res.text();
     let data = null;
     try { data = JSON.parse(raw); } catch { /* non-JSON */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexa-ai",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "AI engine for the Alexa WhatsApp bot: DeepAI-powered chat with PostgreSQL-backed long-term memory, cross-chat identity (@lid <-> phone), vision/OCR, image generation and web search.",
   "main": "index.js",
   "scripts": {

package/src/core/Config.js

@@ -23,6 +23,8 @@ class Config {
      * @param {string} [options.visionModel]       Model used when images are attached
      * @param {string[]} [options.visionModels]    Vision fallback chain
      * @param {string} [options.imageModel]        Model used by generateImage()
+     * @param {string} [options.transport]         /api/* transport: 'auto' (default) | 'fetch' | 'curl' | 'impersonate'
+     * @param {string} [options.curlImpersonatePath] Path to a curl-impersonate binary for the 'impersonate' transport
      * @param {string} [options.assistantName]     Persona name (default 'Alexa')
      * @param {string} [options.creator]           Persona creator (default 'Hansaka')
      * @param {string} [options.systemPrompt]      Override the whole persona text
@@ -112,6 +114,19 @@ class Config {
         ]);
         this.imageModel = opts.imageModel || 'text2img';
 
+        // ---- /api/* transport -------------------------------------------------
+        // 'auto'        fetch first, then system curl, then curl-impersonate
+        //               when the binary is available (some networks serve
+        //               non-browser TLS stacks a refusal page).
+        // 'fetch'       Node global fetch only (previous behaviour)
+        // 'curl'        system curl subprocess only
+        // 'impersonate' curl-impersonate subprocess only (Chrome TLS profile)
+        this.transport = opts.transport || process.env.DEEPAI_TRANSPORT || 'auto';
+        this.curlPath = opts.curlPath || process.env.DEEPAI_CURL || 'curl';
+        this.curlImpersonatePath =
+            opts.curlImpersonatePath || process.env.DEEPAI_CURL_IMPERSONATE || null;
+        this.curlImpersonateTarget = opts.curlImpersonateTarget || 'chrome136';
+
         // ---- Anonymous device identity ---------------------------------------
         // Stable device identifier sent as the `deepai_device_id` cookie.
         // Anonymous /api/* generation is rate-limited per device, so the id

package/src/core/DeepAIClient.js

@@ -615,36 +615,232 @@ class DeepAIClient {
      * @returns {Promise<object>} e.g. `{ id, output_url }`
      */
     async runApi(name, fields = {}, options = {}) {
-        const form = new FormData();
-        for (const [key, value] of Object.entries(fields)) {
+        const url = `${this.config.url('api')}/${String(name).replace(/^\/+/, '')}`;
+        const entries = this._buildApiFields(fields, options);
+        return this._apiFormRequest(url, entries, options);
+    }
+
+    /**
+     * Normalise API form fields into a transport-neutral entry list:
+     * `[[key, { value | buffer, mimetype, filename }], …]`.
+     * @private
+     */
+    _buildApiFields(fields, options = {}) {
+        const entries = [];
+        for (const [key, value] of Object.entries(fields || {})) {
             if (value == null) continue;
-            if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
-                const mimetype = options.mimetype || DeepAIClient._sniffMime(value) || 'application/octet-stream';
-                form.append(key, new Blob([value], { type: mimetype }), options.filename || `${key}.${DeepAIClient._ext(mimetype)}`);
+            if (Buffer.isBuffer(value) || value instanceof Uint8Array || value instanceof Blob) {
+                entries.push([key, { buffer: value, mimetype: options.mimetype, filename: options.filename }]);
             } else if (typeof value === 'object' && (value.buffer || value.url)) {
                 if (value.url && !value.buffer) {
-                    form.append(key, String(value.url));
-                    continue;
+                    entries.push([key, { value: String(value.url) }]);
+                } else {
+                    entries.push([
+                        key,
+                        {
+                            buffer: Buffer.isBuffer(value.buffer) ? value.buffer : Buffer.from(value.buffer),
+                            mimetype: value.mimetype,
+                            filename: value.filename,
+                        },
+                    ]);
                 }
-                const bytes = Buffer.isBuffer(value.buffer) ? value.buffer : Buffer.from(value.buffer);
-                const mimetype = value.mimetype || DeepAIClient._sniffMime(bytes) || 'application/octet-stream';
-                form.append(key, new Blob([bytes], { type: mimetype }), value.filename || `${key}.${DeepAIClient._ext(mimetype)}`);
             } else if (typeof value === 'object') {
-                form.append(key, JSON.stringify(value));
+                entries.push([key, { value: JSON.stringify(value) }]);
             } else {
-                form.append(key, String(value));
+                entries.push([key, { value: String(value) }]);
             }
         }
-        const url = `${this.config.url('api')}/${String(name).replace(/^\/+/, '')}`;
-        const data = await this._json(url, { method: 'POST', body: form, signal: options.signal });
-        // The classic API reports failures as `{ err: "..." }` or `{ status: "..." }` with HTTP 200.
-        if (data?.err) {
-            throw DeepAIClient._toError(200, JSON.stringify(data), String(data.err));
+        return entries;
+    }
+
+    /**
+     * POST a multipart form to a `/api/*` URL across the configured transport
+     * chain. A refusal of the form "Please try this model on deepai.org" can
+     * be transport-specific (non-browser TLS stacks receive it even with a
+     * perfectly valid key), so on that error the next transport is tried;
+     * every other error (quota, auth, network) is final for this request.
+     * @private
+     */
+    async _apiFormRequest(url, entries, options = {}) {
+        const chain = await this._transportChain();
+        let lastError;
+        for (const transport of chain) {
+            try {
+                const raw = await this._runApiTransport(transport, url, entries, options);
+                const data = DeepAIClient._safeJson(raw.body);
+                if (raw.status > 299 || data === null) {
+                    throw DeepAIClient._toError(raw.status, raw.body, data?.status || data?.error);
+                }
+                if (data?.err) {
+                    throw DeepAIClient._toError(200, JSON.stringify(data), String(data.err));
+                }
+                if (typeof data?.status === 'string' && !data.share_url && !data.output_url && !data.output && !data.id) {
+                    throw DeepAIClient._toError(200, JSON.stringify(data), data.status);
+                }
+                return data;
+            } catch (err) {
+                if (DeepAIClient._isTransportRejected(err) && chain.length > 1) {
+                    lastError = err;
+                    if (this.config.debug) this.log.warn?.(`[AlexaAI] ${transport} transport refused for ${url}; trying the next`);
+                    continue;
+                }
+                if (err instanceof QuotaExceededError || err.retryable === false || err.code === 'ABORTED') throw err;
+                throw err;
+            }
         }
-        if (typeof data?.status === 'string' && !data.share_url && !data.output_url && !data.output && !data.id) {
-            throw DeepAIClient._toError(200, JSON.stringify(data), data.status);
+        throw lastError || new DeepAIError('DeepAI request failed', { code: 'DEEPAI_ERROR' });
+    }
+
+    /** @private */
+    static _isTransportRejected(err) {
+        return /try this model on deepai\.org/i.test(String(err?.message || ''));
+    }
+
+    /** Ordered transport list for /api/* calls. @private */
+    async _transportChain() {
+        const t = this.config.transport;
+        if (t === 'fetch') return ['fetch'];
+        if (t === 'curl') return ['curl'];
+        if (t === 'impersonate') return ['impersonate'];
+        const chain = ['fetch', 'curl'];
+        if (await DeepAIClient.resolveImpersonateBinary(this.config)) chain.push('impersonate');
+        return chain;
+    }
+
+    /** @private */
+    async _runApiTransport(transport, url, entries, options) {
+        if (transport === 'fetch') return this._runApiFetch(url, entries, options);
+        const impersonate = transport === 'impersonate';
+        const binary = impersonate
+            ? await DeepAIClient.resolveImpersonateBinary(this.config)
+            : this.config.curlPath;
+        return this._runApiCurl(binary, url, entries, options, { impersonate });
+    }
+
+    /** @private global-fetch transport (previous behaviour). */
+    async _runApiFetch(url, entries, options = {}) {
+        const form = new FormData();
+        for (const [key, field] of entries) {
+            if (field.buffer != null) {
+                const bytes = field.buffer instanceof Blob ? Buffer.from(await field.buffer.arrayBuffer()) : field.buffer;
+                const mimetype = field.mimetype || DeepAIClient._sniffMime(bytes) || 'application/octet-stream';
+                form.append(key, new Blob([bytes], { type: mimetype }), field.filename || `${key}.${DeepAIClient._ext(mimetype)}`);
+            } else {
+                form.append(key, field.value);
+            }
+        }
+        const data = await this._json(url, { method: 'POST', body: form, signal: options.signal, errorCode: 'BAD_RESPONSE' });
+        return { status: 200, body: JSON.stringify(data) };
+    }
+
+    /**
+     * The User-Agent a curl-impersonate binary sends for the configured
+     * target profile. The anonymous key hash must be derived from the exact
+     * UA the request carries, so impersonated requests use the profile's own
+     * UA instead of `config.userAgent`.
+     * @private
+     */
+    static _impersonateUserAgent(target) {
+        const m = /chrome(\d+)/i.exec(String(target || ''));
+        const v = m ? m[1] : '136';
+        return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v}.0.0.0 Safari/537.36`;
+    }
+
+    /** @private curl / curl-impersonate subprocess transport. */
+    async _runApiCurl(binary, url, entries, options = {}, { impersonate = false } = {}) {
+        const ua = impersonate ? DeepAIClient._impersonateUserAgent(this.config.curlImpersonateTarget) : this.config.userAgent;
+        const apiKey = DeepAIClient.isTryItKey(this.apiKey)
+            ? DeepAIClient.generateTryItKey(ua)
+            : this.apiKey;
+
+        const args = impersonate ? ['--impersonate', this.config.curlImpersonateTarget] : [];
+        args.push(
+            url,
+            '-sS', '--compressed',
+            '--max-time', String(Math.max(1, Math.round(this.config.timeout / 1000))),
+            '-X', 'POST',
+            '-H', `api-key: ${apiKey}`,
+            '-H', `User-Agent: ${ua}`,
+            '-H', `Origin: ${this.config.origin}`,
+            '-H', `Referer: ${this.config.origin}/machine-learning-model/${this.config.imageModel}`,
+            '-H', 'Accept: */*',
+            '-H', 'Accept-Language: en-US,en;q=0.9',
+            '-w', '\n%{http_code}'
+        );
+        if (this.deviceId) args.push('-H', `Cookie: deepai_device_id=${this.deviceId}`);
+
+        const tmpFiles = [];
+        try {
+            for (const [key, field] of entries) {
+                if (field.buffer != null) {
+                    const bytes = field.buffer instanceof Blob ? Buffer.from(await field.buffer.arrayBuffer()) : field.buffer;
+                    const mimetype = field.mimetype || DeepAIClient._sniffMime(bytes) || 'application/octet-stream';
+                    const ext = DeepAIClient._ext(mimetype);
+                    const tmp = require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'alexa-')) + `/${key}.${ext}`;
+                    require('fs').writeFileSync(tmp, bytes);
+                    tmpFiles.push(tmp);
+                    args.push('-F', `${key}=@${tmp};type=${mimetype}`);
+                } else {
+                    args.push('-F', `${key}=${field.value}`);
+                }
+            }
+            const out = await DeepAIClient.execCurl(binary, args, this.config.timeout, options.signal);
+            const body = String(out).replace(/\r/g, '');
+            const idx = body.lastIndexOf('\n');
+            const status = Number(body.slice(idx + 1).trim());
+            if (!Number.isFinite(status)) {
+                throw new DeepAIError(`curl transport failed for ${url}: ${body.slice(0, 200)}`, {
+                    code: 'DEEPAI_NETWORK', retryable: true,
+                });
+            }
+            return { status, body: body.slice(0, idx) };
+        } finally {
+            for (const f of tmpFiles) { try { require('fs').unlinkSync(f); } catch { /* best effort */ } try { require('fs').rmSync(require('path').dirname(f), { recursive: true, force: true }); } catch { /* best effort */ } }
+        }
+    }
+
+    /**
+     * Locate a curl-impersonate binary: explicit path, then the usual
+     * executable names on PATH. Cached per path. Tests may override.
+     * @private
+     */
+    static async resolveImpersonateBinary(config) {
+        if (config.curlImpersonatePath) return config.curlImpersonatePath;
+        if (config._noImpersonateBinary) return null;
+        if (!DeepAIClient._impersonateCache) {
+            const { execFile } = require('child_process');
+            const names = process.platform === 'win32' ? ['curl-impersonate.exe', 'curl-impersonate'] : ['curl-impersonate'];
+            DeepAIClient._impersonateCache = new Promise((resolve) => {
+                let i = 0;
+                const tryNext = () => {
+                    if (i >= names.length) return resolve(null);
+                    const name = names[i++];
+                    execFile(name, ['--version'], { timeout: 5000 }, (err) => resolve(err ? tryNext() : name));
+                };
+                tryNext();
+            });
         }
-        return data;
+        return DeepAIClient._impersonateCache;
+    }
+
+    /**
+     * Run a curl-compatible binary and capture stdout. Separated so tests
+     * can stub the subprocess layer.
+     * @private
+     */
+    static async execCurl(binary, args, timeoutMs, signal) {
+        const { execFile } = require('child_process');
+        return new Promise((resolve, reject) => {
+            const child = execFile(binary, args, { timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+                if (err && stdout == null) return reject(new DeepAIError(`curl transport error: ${err.message}`, { code: 'DEEPAI_NETWORK', retryable: true }));
+                resolve(stdout != null ? stdout : '');
+                void stderr;
+            });
+            if (signal) {
+                if (signal.aborted) child.kill();
+                else signal.addEventListener('abort', () => child.kill(), { once: true });
+            }
+        });
     }
 
     /** Text-to-image (`/api/text2img`). Returns `{ id, output_url }`. */

package/test/run-tests.js

@@ -708,7 +708,98 @@ section('DeepAIClient — the whole endpoint surface (mocked transport)');
         );
         ok('share_url is preferred over output_url', result.url === 'https://deepai.org/generated-image.png');
     }
-    const cfg = new Config({ key: 'k', postgresUrl: 'postgres://u:p@localhost/db' });
+    
+{
+    section('DeepAIClient — /api transport chain');
+
+    const realFetch = global.fetch;
+    const realExecCurl = DeepAIClient.execCurl;
+    const realCache = DeepAIClient._impersonateCache;
+
+    // 1. a transport-specific refusal ("Please try this model") falls through
+    //    to the next transport (fetch -> curl).
+    {
+        let curlCall = null;
+        global.fetch = async () => ({
+            status: 401,
+            headers: { get: () => 'application/json' },
+            text: async () => JSON.stringify({ status: 'Please try this model on deepai.org' }),
+        });
+        DeepAIClient.execCurl = async (bin, args) => {
+            curlCall = { bin, args };
+            return '{"id":"t1","share_url":"https://deepai.org/x.png"}\n200';
+        };
+        DeepAIClient._impersonateCache = Promise.resolve(null);
+        const client = new DeepAIClient(new Config({ key: 'tryit-1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', postgresUrl: 'postgres://u:p@localhost/db', maxRetries: 0 }));
+        const data = await client.runApi('text2img', { text: 'cat', generation_source: 'img' });
+        check('curl transport recovers a fetch refusal', data.share_url, 'https://deepai.org/x.png');
+        ok('curl transport received the form fields', curlCall.args.includes('text=cat') && curlCall.args.includes('generation_source=img'));
+        const key = curlCall.args.find((a) => a.startsWith('api-key: ')).slice(9);
+        ok('curl transport used a fresh anonymous key', DeepAIClient.isTryItKey(key));
+        ok('curl transport sends the Origin header', curlCall.args.includes('Origin: https://deepai.org'));
+    }
+
+    // 2. quota refusals are final — no transport cascade.
+    {
+        let curlCalled = false;
+        global.fetch = async () => ({
+            status: 402,
+            headers: { get: () => 'application/json' },
+            text: async () => JSON.stringify({ status: 'APIs are only available for Pro members in good standing' }),
+        });
+        DeepAIClient.execCurl = async () => { curlCalled = true; return '{}\n200'; };
+        const client = new DeepAIClient(new Config({ key: 'k', postgresUrl: 'postgres://u:p@localhost/db', maxRetries: 0 }));
+        let thrown = null;
+        try { await client.runApi('text2img', { text: 'cat' }); } catch (e) { thrown = e; }
+        ok('quota refusal throws QuotaExceededError', thrown?.name === 'QuotaExceededError' || thrown?.code === 'DEEPAI_QUOTA_EXCEEDED');
+        ok('no other transport is tried on quota refusals', curlCalled === false);
+    }
+
+    // 3. the impersonate transport uses the profile UA and derives the key
+    //    hash from it.
+    {
+        let call = null;
+        DeepAIClient.execCurl = async (bin, args) => { call = { bin, args }; return '{"id":"t2","output_url":"https://deepai.org/y.png"}\n200'; };
+        const client = new DeepAIClient(new Config({
+            key: 'tryit-1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+            postgresUrl: 'postgres://u:p@localhost/db',
+            transport: 'impersonate',
+            curlImpersonatePath: '/fake/curl-impersonate',
+            maxRetries: 0,
+        }));
+        const data = await client.runApi('text2img', { text: 'cat' });
+        check('impersonate transport returns the image', data.output_url, 'https://deepai.org/y.png');
+        check('impersonate binary and profile are passed', [call.bin, call.args[0], call.args[1]], ['/fake/curl-impersonate', '--impersonate', 'chrome136']);
+        const ua = call.args.find((a) => a.startsWith('User-Agent: ')).slice(12);
+        const key = call.args.find((a) => a.startsWith('api-key: ')).slice(9);
+        const m = /^tryit-(\d+)-([0-9a-f]{32})$/.exec(key);
+        const H = DeepAIClient._islandHash;
+        const salt = 'hackers_become_a_little_stinkier_every_time_they_hack';
+        ok('impersonate key hash matches the profile User-Agent', m && m[2] === H(ua + H(ua + H(ua + m[1] + salt))));
+    }
+
+    // 4. transport:'fetch' never spawns a subprocess.
+    {
+        let curlCalled = false;
+        global.fetch = async () => ({
+            status: 401,
+            headers: { get: () => 'application/json' },
+            text: async () => JSON.stringify({ status: 'Please try this model on deepai.org' }),
+        });
+        DeepAIClient.execCurl = async () => { curlCalled = true; return '{}\n200'; };
+        const client = new DeepAIClient(new Config({ key: 'k', postgresUrl: 'postgres://u:p@localhost/db', transport: 'fetch', maxRetries: 0 }));
+        let thrown = null;
+        try { await client.runApi('text2img', { text: 'cat' }); } catch (e) { thrown = e; }
+        ok('fetch-only transport surfaces the refusal', thrown && /try this model/i.test(thrown.message));
+        ok('fetch-only transport never shells out', curlCalled === false);
+    }
+
+    global.fetch = realFetch;
+    DeepAIClient.execCurl = realExecCurl;
+    DeepAIClient._impersonateCache = realCache;
+}
+
+const cfg = new Config({ key: 'k', postgresUrl: 'postgres://u:p@localhost/db' });
     check('endpoint map exposes the chat route', cfg.url('chat'), 'https://api.deepai.org/hacking_is_a_serious_crime');
     check(
         'endpoint map builds query strings',