Web 應用程式整合 DeepAI Text-to-Image API 完全指南：金鑰鑑權、REST 接口與生產級架構實踐

在現代 Web 應用程式中引入 AI 影像生成技術，能為使用者提供個人化頭像建立、社群行銷素材繪製及視覺內容創作等功能。然而，對於獨立開發者與初創團隊來說，自行建置與維護 GPU 推理伺服器（例如維護 Stable Diffusion 實例、CUDA 驅動程式以及處理冷啟動和負載平衡）往往面臨龐大的初期建置成本與繁雜的運維工作。

DeepAI 提供了解決方案：透過其 Text-to-Image REST API，開發者無需涉足任何底層算力硬體，僅需透過標準 HTTP POST 請求傳遞提示詞與樣式參數，即可迅速產出高品質影像。本文將深入剖析此 API 的技術規格、金鑰鑑權設定、前後端協同架構與生產級整合注意事項。

架構設計：為何必須採用後端代理模式？

許多初次整合第三方 AI 服務的開發者，容易嘗試直接從前端瀏覽器（例如 React、Vue 或原生 fetch）呼叫 DeepAI API。然而，DeepAI 透過靜態 API Key 進行請求鑑權；若直接在前端發送請求，API 金鑰將毫無保留地暴露在瀏覽器的 Network 標籤頁與客戶端程式碼封裝中，極易招致惡意盜用與配額被刷盡的風險。

符合生產標準的架構必須實施後端代理模式（Backend Proxy Pattern）：

[前端瀏覽器 UI]
       │
       ▼  (1) POST /api/generate-image { prompt, style, width, height }
[業務後端伺服器 (Node.js / Next.js / Python)]
       │  - 驗證使用者登入狀態、輸入有效性與請求頻率
       │  - 自環境變數讀取 process.env.DEEPAI_API_KEY
       ▼  (2) POST https://api.deepai.org/api/text2img (Header: api-key)
[DeepAI 推理伺服器群]
       │
       ▼  (3) 回傳 JSON { id, output_url }
[業務後端伺服器]
       │  - 選用：非同步轉存至自有物件儲存 (S3 / Cloudflare R2)
       ▼  (4) 回傳 { imageUrl, id } 給前端
[前端瀏覽器 UI]

採用後端代理不僅能確保金鑰安全，還能讓後端統一實施業務級限流、內容過濾，以及對生成影像進行持久化轉存。

DeepAI Text-to-Image REST API 規範詳解

DeepAI 的文字生圖服務提供單一 REST 端點，同時相容 application/json 與 multipart/form-data 的請求主體格式。

請求端點與身分鑑權

• 端點位址： POST https://api.deepai.org/api/text2img
• 鑑權標頭： api-key: YOUR_API_KEY
• 標頭格式重點： DeepAI 採用自訂標頭名稱 api-key，而非業界標準的 Authorization: Bearer <token>。若誤用 Bearer 格式，伺服器將拒絕請求並回傳 HTTP 401 Unauthorized。

請求參數列表

長寬比與尺寸建議：

• 標準模式（Standard）： 512x512（正方形）、1024x576（16:9 橫向）、576x1024（9:16 直向）、1024x720、768x1024。在 Standard 模式下設定超過 700 像素可能偶發結構變形，需要更高細節建議切換至 hd 或 genius。
• 高清模式（HD）： 1024x1024（正方形）、1216x832（橫向）、832x1216（直向）、1152x896、896x1152。

成功回傳資料結構

生成完成後，API 會以同步方式回傳 HTTP 200 OK 及 JSON 響應：

{
  "id": "59a0e8a9-1123-44b2-9a8c-7981b2345678",
  "output_url": "https://api.deepai.org/job-view-file/59a0e8a9-1123-44b2-9a8c-7981b2345678/output.jpg"
}

• id: 本次生圖任務的唯一 UUID 識別碼。
• output_url: 託管於 DeepAI 伺服器上的 JPG 影像完整直連網址。

生產級程式碼實作示範

本節以 Node.js（Express）後端與現代瀏覽器原生 JavaScript 前端為例，示範完整的參數封裝、錯誤攔截與前端載入狀態維護。

1. 伺服器端路由實作（Node.js / Express 範例）

在伺服器環境設定變數 DEEPAI_API_KEY，並使用 Fetch API 轉發請求：

// server/routes/imageGenRoute.js
import express from 'express';

const router = express.Router();

router.post('/generate-image', async (req, res) => {
  try {
    const { prompt, style = 'standard', width = '512', height = '512', negativePrompt } = req.body;

    if (!prompt || typeof prompt !== 'string' || prompt.trim().length === 0) {
      return res.status(400).json({ error: '必須提供有效的提示詞內容。' });
    }

    const apiKey = process.env.DEEPAI_API_KEY;
    if (!apiKey) {
      return res.status(500).json({ error: '伺服器設定錯誤：找不到 DeepAI API Key。' });
    }

    // 封裝發送給 DeepAI 的資料
    const payload = {
      text: prompt.trim(),
      image_generator_version: style,
      width: String(width),
      height: String(height)
    };

    if (negativePrompt) {
      payload.negative_prompt = negativePrompt.trim();
    }

    // 發送 POST 請求至 DeepAI REST API，設定 30 秒逾時中斷機制
    const response = await fetch('https://api.deepai.org/api/text2img', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'api-key': apiKey
      },
      body: JSON.stringify(payload),
      signal: AbortSignal.timeout(30000)
    });

    const data = await response.json();

    if (!response.ok) {
      const errorMessage = data.err || data.status || 'DeepAI 遠端服務異常';
      return res.status(response.status).json({ error: errorMessage });
    }

    // 回傳圖片網址與任務 ID
    return res.status(200).json({
      success: true,
      id: data.id,
      imageUrl: data.output_url
    });
  } catch (error) {
    if (error.name === 'TimeoutError') {
      return res.status(504).json({ error: '圖片生成超時，請稍後重試。' });
    }
    return res.status(500).json({ error: '伺服器處理生圖請求時發生非預期錯誤。' });
  }
});

export default router;

2. 客戶端請求與 UI 互動狀態控制

生圖運算需要一定推理時間（通常約 2 至 8 秒），前端必須提供適當的進度提示，並阻絕重複點擊：

// client/app.js
async function requestAiImage(promptText) {
  const submitBtn = document.getElementById('btn-generate');
  const previewArea = document.getElementById('preview-box');
  const statusLabel = document.getElementById('status-text');

  try {
    // 進入等待載入狀態
    submitBtn.disabled = true;
    statusLabel.textContent = 'AI 繪圖處理中，請稍候（約 3-6 秒）...';
    previewArea.classList.add('loading-skeleton');

    const response = await fetch('/api/generate-image', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: promptText,
        style: 'standard',
        width: '512',
        height: '512',
        negativePrompt: 'blurry, deformed, bad anatomy, watermark'
      })
    });

    const result = await response.json();

    if (!response.ok) {
      throw new Error(result.error || `請求失敗，狀態碼 ${response.status}`);
    }

    // 呈現生圖結果
    previewArea.innerHTML = `<img src="${result.imageUrl}" alt="${promptText}" class="image-render" />`;
    statusLabel.textContent = '影像生成完畢！';
  } catch (err) {
    statusLabel.textContent = `錯誤：${err.message}`;
  } finally {
    submitBtn.disabled = false;
    previewArea.classList.remove('loading-skeleton');
  }
}

異常狀態碼應對與韌性防護

在線上環境調用 DeepAI API 時，應建立精準的錯誤監控與處置機制：

• 401 Unauthorized： 未提供 api-key、金鑰無效，或目前帳號的 Pro 訂閱配額已用盡且未啟用自動加值。後端應觸發系統告警以提醒維運人員。
• 402 Payment Required： 帳號預付餘額不足。建議於 DeepAI 後台啟用 Auto Top-up，確保在尖峰流量下業務不中斷。
• 400 Bad Request / 內容安全攔截： 參數格式錯誤，或提示詞內容觸發了 DeepAI 的內容審核機制（NSFW 敏感詞篩選）。前端應引導使用者修改提示詞。
• 500 Internal Server Error： DeepAI 叢集發生瞬時推理異常。後端可設定指數退避（Exponential Backoff）重試機制。
• 伺服器逾時防護： Text-to-Image 是同步 HTTP 請求，尖峰負載時連線可能維持 5 至 10 秒。若使用 Vercel 或 AWS Lambda 等 Serverless 架構，需確保函式最大逾時時間（Execution Timeout）設定為 25 秒以上。

永久儲存：轉存自有物件儲存與 CDN

DeepAI 傳回的 output_url 屬於第三方託管網址。若長期直接依賴外部連結，可能會面臨外部檔案過期失效、連線延遲或 CORS 存取限制等隱憂。

生產級系統的最佳實踐為：當後端收到 output_url 後，以串流方式將圖片下載並轉存至自家雲端儲存（如 AWS S3、Cloudflare R2 或 Google Cloud Storage），並綁定自身的 CDN 域名回傳給前端。這不僅能確保資產永久受控，還能依業務需求進行 WebP/AVIF 自動轉換與快取加速。

費用架構與技術選型權衡

呼叫 DeepAI API 需具備 DeepAI Pro 訂閱（每月 9.99 美元或每年 89.99 美元）。訂閱提供基本配額，超出後依用量扣款：

• 標準版（Standard）： 約 $0.01 / 張
• Genius 模式： 約 $0.08 / 張
• Super Genius 模式： 約 $0.25 / 張（2K 解析度與更高藝術細節）

適用時機

DeepAI 非常適合獨立開發者、新創產品原型（MVP）以及中小型 Web 平台。它完全免除了 GPU 伺服器租賃、驅動更新及 Kubernetes 叢集擴展的維運負擔，計費透明且即開即用。

自建模型的評估邊界

如果業務具有高度特定的客製化訴求（如指定微調 LoRA 模型、搭配 ControlNet 精確控制肢體），或每月生圖規模超過十萬張、自建專用 GPU 執行個體的邊際成本更具優勢時，才需要考慮自行架設 Diffusers/ComfyUI 伺服器。

對於追求敏捷開發與穩定服務的 Web 應用而言，DeepAI REST API 提供了在開發效率、成本投入與生成品質之間的平衡選擇。

參考資料

• DeepAI Docs
• AI Image Generator
• Pricing | DeepAI