跳到內容
繁體中文

API 端點參考

目前 API 供同來源、已登入的工作台使用。以下為實際端點與主要欄位範例，ID 需替換為帳戶內的資料。

驗證方式與快速開始 →
base url
本機：http://localhost:18970/api/v1
已部署環境：使用目前站點的 /api/v1

取得儲值方案與付款方式

GET/customer/billing/products

回傳方案、積分充值及四種支付。只有已配置、啟用且符合環境限制的方式才可結帳；客戶不會收到商戶憑證。

http
GET /api/v1/customer/billing/products HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

建立付款訂單

POST/customer/billing/checkout

先在伺服器建立可追蹤訂單，再建立供應商付款頁。金額、幣別與積分都由產品資料決定，不接受客戶自訂。相同 UUID 不會建立第二張訂單。

http
POST /api/v1/customer/billing/checkout HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "product_key": "topup_250k",
  "gateway": "stripe"
}

回應範例（主要欄位）

json
{
  "transaction": {
    "id": 91,
    "revision": 2,
    "gateway": "stripe",
    "mode": "sandbox",
    "status": "pending",
    "amount": 20,
    "currency": "USD",
    "credits": 250000
  },
  "checkout_url": "https://checkout.stripe.com/c/pay/<session>",
  "display_message": "訂單已建立，請前往付款。"
}

gateway 可為 stripe、paypal、airwallex、epusdt。attention 代表建立結果不明；先查詢與對帳，勿用新 UUID 重做。

查詢付款訂單

GET/customer/billing/transactions/{order}

唯讀本機訂單狀態，可每 5 秒輪詢。網址 query、返回頁或客戶傳入的 success 都不能作為入帳憑證。

http
GET /api/v1/customer/billing/transactions/{order} HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

向供應商查單確認

POST/customer/billing/transactions/{order}/confirm

帶最新 revision 及 UUID。伺服器向供應商查單；PayPal 在買家已批准後執行 capture。金額、幣別、訂單識別核對成功後才入帳。

http
POST /api/v1/customer/billing/transactions/{order}/confirm HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 2
}

回應範例（主要欄位）

json
{
  "transaction": {
    "id": 91,
    "revision": 3,
    "status": "paid",
    "amount": 20,
    "currency": "USD",
    "credits": 250000
  }
}

付款成功通知和此 API 同時到達，也只會入帳一次。付款通知專用路徑為 POST /api/v1/payments/webhooks/{gatewaySettingId}，由支付平台呼叫，使用供應商簽章驗證，不使用使用者 Session／CSRF。

取得可用模型

GET/customer/ai-models

依帳戶可用來源回傳模型。建立內容計畫與生成文章時使用 model_key。

http
GET /api/v1/customer/ai-models HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "models": [
    {
      "model_key": "gemini-2.5-flash",
      "name": "Gemini 2.5 Flash",
      "type": "text"
    }
  ]
}

取得工作空間

GET/customer/workspaces

取得目前租戶的發布工作空間；建立文章不要求先連接工作空間。

http
GET /api/v1/customer/workspaces HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "workspaces": {
    "items": [
      {
        "id": 12,
        "revision": 1,
        "name": "品牌官網",
        "destination_type": "wordpress",
        "default_publish_status": "draft",
        "has_connection": true
      }
    ]
  }
}

建立內容計畫

POST/customer/content-plans

依提示詞建議選題。需要即時來源時開啟 web_research；選題 ID 由回應中的 plan.topics 取得。

http
POST /api/v1/customer/content-plans HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>
欄位類型說明
ai_model_keystring · 必填使用模型清單的 model_key。
request_textstring · 必填使用者需求，最多 6000 字元。
workspace_idinteger | null可省略；發布工作空間 ID。
topic_countinteger · 必填1–20 個選題。
web_researchboolean是否參考網際網路資料。

請求 JSON

json
{
  "ai_model_key": "gemini-2.5-flash",
  "workspace_id": null,
  "request_text": "寫一篇關於特斯拉的新聞",
  "language": "zh_TW",
  "tone": "專業、清楚、自然",
  "sync_mode": "standard",
  "workflow_mode": "standard",
  "source_mode": "wordpress_ai",
  "image_mode": "none",
  "topic_count": 10,
  "web_research": true
}

文字與圖片生成會依帳戶規則計費；請先在工作台確認預估積分。

為選題生成大綱

POST/customer/content-topics/{topic}/prepare

路徑 topic 是內容計畫回傳的選題 ID。如需變更標題，先 PATCH /customer/content-topics/{topic}，傳入 title 與 revision，再準備大綱。

http
POST /api/v1/customer/content-topics/{topic}/prepare HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "ai_model_key": "gemini-2.5-flash"
}

逐段生成文章與圖片

POST/customer/generations

只提交使用者選取並排序後的段落。paragraph_images 為 true 時，每段生成一張圖片。Idempotency-Key 同時用於查詢生成進度。

http
POST /api/v1/customer/generations HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "content_topic_id": 41,
  "ai_model_key": "gemini-2.5-flash",
  "selected_title": "特斯拉公布季度交付數據",
  "outline": [
    {
      "heading": "交付數據與已確認事實",
      "notes": "引用所選新聞來源"
    },
    {
      "heading": "與前期數據比較",
      "notes": "只使用來源中可核實的數據"
    },
    {
      "heading": "後續觀察重點",
      "notes": "區分已知事實與預測"
    }
  ],
  "image_mode": "none",
  "paragraph_images": true,
  "image_ratio": "16:9",
  "image_style": "editorial"
}

這是可能耗時的生成請求。HTTP 中斷後，先以原 UUID 查詢進度；不要直接用新 UUID 重做整篇文章。

查詢生成進度

GET/customer/generations/{key}/progress

key 使用生成請求的 Idempotency-Key UUID。

http
GET /api/v1/customer/generations/{key}/progress HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "stage": "writing",
  "status": "processing",
  "completed": 1,
  "total": 3,
  "current_section": "與前期數據比較",
  "completed_images": 1
}

分頁查詢文章

GET/customer/posts?page=1&per_page=10&status=draft

status 可用 all、draft、sent、generation_failed、archived；workspace_id 篩選工作空間，unassigned=1 篩選未指定工作空間的文章。

http
GET /api/v1/customer/posts?page=1&per_page=10&status=draft HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "posts": {
    "items": [
      {
        "id": 81,
        "revision": 2,
        "title": "特斯拉公布季度交付數據",
        "status": "draft",
        "workspace_id": null
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 10,
      "total": 1,
      "from": 1,
      "to": 1
    }
  },
  "permissions": {
    "can_archive": true,
    "can_delete": false
  }
}

讀取文章

GET/customer/posts/{post}

取得正文、圖片、校對狀態與最新 revision，編輯前先讀取此端點。

http
GET /api/v1/customer/posts/{post} HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "post": {
    "id": 81,
    "revision": 2,
    "title": "特斯拉公布季度交付數據",
    "content": "<h2>交付數據與已確認事實</h2><p>文章內容。</p>",
    "excerpt": "文章摘要",
    "status": "draft",
    "quality_status": "pending"
  }
}

儲存文章

PATCH/customer/posts/{post}

需帶最新 revision。正文由伺服器淨化，內容變更後需要重新校對才能發布。

http
PATCH /api/v1/customer/posts/{post} HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 2,
  "title": "特斯拉公布季度交付數據",
  "excerpt": "文章摘要",
  "content": "<h2>交付數據與已確認事實</h2><p>已核實的文章內容。</p>"
}

回應範例（主要欄位）

json
{
  "post": {
    "id": 81,
    "revision": 3,
    "title": "特斯拉公布季度交付數據",
    "status": "draft"
  }
}

AI 改寫段落

POST/customer/posts/{post}/rewrite

回傳改寫文字，不會直接覆蓋已儲存的文章；接受結果後再呼叫儲存文章。

http
POST /api/v1/customer/posts/{post}/rewrite HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 3,
  "ai_model_key": "gemini-2.5-flash",
  "heading": "交付數據與已確認事實",
  "section": "原始段落文字",
  "instruction": "語句更精簡，保留來源與數據"
}

上傳文章圖片

POST/customer/posts/{post}/images

使用 multipart/form-data，欄位 file 為圖片、revision 為文章版本；此端點不要手動指定 JSON Content-Type。僅接受 PNG、JPEG、WebP，最大 5 MiB，重新解碼及編碼後保存。

http
POST /api/v1/customer/posts/{post}/images HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data; boundary=<boundary>
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>
欄位類型說明
filebinary · 必填圖片檔案，最大 1600 萬像素、任一邊不超過 10000px。
revisioninteger · 必填目前文章 revision。

回傳 image.url 可用於此文章正文。跨文章、跨租戶及任意外部圖片網址會被拒絕。每篇最多 40 張，租戶上傳空間 200 MB。

執行發布前校對

POST/customer/posts/{post}/review

檢查文章、標題及參考來源。發布前必須通過校對，且之後沒有修改相關內容。

http
POST /api/v1/customer/posts/{post}/review HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 3,
  "ai_model_key": "gemini-2.5-flash"
}

送到工作空間

POST/customer/posts/{post}/publish

依工作空間的發布類型送出文章。publish_status 可省略，沿用工作空間預設；需要可指定 draft 或 publish。

http
POST /api/v1/customer/posts/{post}/publish HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 4,
  "workspace_id": 12,
  "publish_status": "draft"
}

遠端回應不明時先查文章與執行紀錄，避免用新 UUID 重複發布。

封存文章

POST/customer/posts/{post}/archive

使用者可封存文章，相關扣費及歷史保留。具有刪除權限的管理員可用 DELETE /customer/posts/{post}，同樣帶 revision。

http
POST /api/v1/customer/posts/{post}/archive HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 4
}

取得寫作流程

GET/customer/post-presets

列出可用的寫作流程，新增排程時以 post_preset_id 指定流程。

http
GET /api/v1/customer/post-presets HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "presets": {
    "items": [
      {
        "id": 21,
        "revision": 1,
        "name": "每日產業新聞",
        "ai_model_key": "gemini-2.5-flash",
        "section_count": 3
      }
    ]
  }
}

建立排程

POST/customer/schedules

建立後預設暫停，需另行啟用。時間統一依伺服器時區，無需提供 timezone。寫作流程、工作空間與模型都必須屬於目前可使用的範圍。

http
POST /api/v1/customer/schedules HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>
欄位類型說明
post_preset_idinteger · 必填寫作流程 ID。
namestring · 必填排程名稱，最多 180 字元。
frequencystring · 必填daily / weekly / monthly / cron。
run_atstring · 必填HH:mm，採用伺服器時間。
schedule_configobject · 必填every_days 1–366；weekly 使用 weekday 0–6；monthly 使用 month_day 1–31。
cron_expressionstringfrequency=cron 時必填；五欄 Cron 表達式。

請求 JSON

json
{
  "post_preset_id": 21,
  "name": "每日產業新聞",
  "frequency": "daily",
  "run_at": "09:00",
  "schedule_config": {
    "every_days": 1,
    "publish_status": "draft"
  }
}

回應範例（主要欄位）

json
{
  "schedule": {
    "id": 31,
    "revision": 1,
    "name": "每日產業新聞",
    "status": "paused",
    "is_active": false,
    "timezone": "UTC",
    "last_run_at": null,
    "next_run_at": null
  }
}

取得排程清單

GET/customer/schedules

最後執行時間包含已開始但失敗或取消的執行嘗試；暫停且沒有待執行時間的排程回傳 next_run_at=null。

http
GET /api/v1/customer/schedules HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "schedules": {
    "items": [
      {
        "id": 31,
        "revision": 1,
        "name": "每日產業新聞",
        "is_active": false,
        "generated_posts_count": 0,
        "published_posts_count": 0,
        "last_run_at": null,
        "next_run_at": null,
        "last_failure_reason": null
      }
    ]
  }
}

啟用、暫停或執行一次

POST/customer/schedules/{schedule}/automation/{action}

action 為 enable、pause 或 run。enable 會驗證模型可用性並計算下次執行時間；pause 停用排程並取消尚未開始的任務。run 立即加入背景佇列，可能產生文章、扣點及發布。

http
POST /api/v1/customer/schedules/{schedule}/automation/{action} HTTP/1.1
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <csrf-token>
Idempotency-Key: <uuid>
Cookie: <session-cookie>

請求 JSON

json
{
  "revision": 1
}

回應範例（主要欄位）

json
{
  "schedule": {
    "id": 31,
    "revision": 2,
    "is_active": true,
    "status": "active",
    "timezone": "UTC",
    "next_run_at": "2026-11-01T09:00:00+00:00"
  }
}

HTTP 409 可能代表 revision 過期，或已有待執行／待確認的任務。先讀取最新資料，勿盲目重試。

取得執行紀錄

GET/customer/automation-runs

查詢最近的背景任務。status 包含 queued、processing、completed、failed、attention、cancelled；attention 代表發布結果需確認。

http
GET /api/v1/customer/automation-runs HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "runs": [
    {
      "id": "9c5a7a92-a62a-4ff9-921f-5806be34797f",
      "schedule_id": 31,
      "status": "completed",
      "stage": "publish",
      "attempts": 1,
      "article_id": 81,
      "scheduled_for": "2026-11-01T09:00:00+00:00",
      "error_code": null
    }
  ]
}

取得伺服器時間

GET/customer/system/clock

所有排程共用伺服器時區；日期時間回傳 ISO 8601。工作台左下角會顯示此時鐘。

http
GET /api/v1/customer/system/clock HTTP/1.1
Accept: application/json
Cookie: <session-cookie>

回應範例（主要欄位）

json
{
  "server_time": "2026-11-01T08:30:00+00:00",
  "timezone": "UTC"
}
新文章AI