跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

報告生成

⚠️

Beta 預覽版
Report Generation API 目前位於 /beta 路徑下,屬於預覽版功能。API 介面、欄位、處理行為及回應格式可能隨產品迭代調整(包含但不限於變更規格、移除功能),APMIC 不保證其向下相容性。

報告用於根據已建立完成的報告模板與指定的知識版本(Fileset),自動產生一份完整報告。系統會依照模板的撰寫指引逐章節檢索資料並生成內容,經使用者確認後套回模板版面,最後可匯出為 PDF。
系統會依序完成以下處理:

  • 草稿生成:依照模板的 writing_guidelines,逐章節執行知識庫檢索與內容撰寫,產生 draft。

  • 草稿確認:由使用者檢視或修改各章節內容後回傳,作為套版依據。

  • 模板填充:將確認後的章節內容拆解為模板的各個 slot,並渲染為完整的 rendered_html。

  • 報告匯出:將完成的報告轉換為 PDF 檔案,並透過 Files API 取得檔案。

建立報告前,請先完成報告模板(狀態為 completed,詳見「建立報告模板」章節),並準備好要作為資料來源的 Fileset。


API 一覽​

功能MethodEndpoint
建立報告POST/beta/report-generation/reports
取得報告GET/beta/report-generation/reports/{report_id}
確認報告草稿POST/beta/report-generation/reports/{report_id}/confirm
匯出報告POST/beta/report-generation/reports/{report_id}/export
刪除報告DELETE/beta/report-generation/reports/{report_id}

操作流程​

準備已完成的報告模板與 Fileset
↓
建立報告(state: generating_draft)
↓
系統逐章節生成草稿(完成後 state: pending_review,發送 Webhook)
↓
取得並確認或修改草稿(state: filling_template)
↓
系統填充模板並渲染(完成後 state: completed,發送 Webhook)
↓
匯出 PDF

建立報告時,模板內容是以 template 物件直接帶入,而非傳入 template_id。請先透過報告模板 API 取得模板內容:

GET /beta/report-generation/templates/{template_id}?expand=jinja_html,writing_guidelines

再將取得的 jinja_html 與 writing_guidelines 放入建立報告的 template 欄位。writing_guidelines 只有在模板狀態為 completed 時才會回傳。


1. 建立報告​

建立一份新的報告,並啟動非同步草稿生成程序。

Endpoint​

POST /beta/report-generation/reports

建立成功後回傳 201 Created,報告狀態會先進入:

generating_draft

草稿生成完成後,狀態會轉為:

pending_review

若有設定 webhook_url,系統會在草稿生成完成或失敗時傳送通知。


Request Headers​

HeaderValue
AuthorizationBearer <your-api-key>
Content-Typeapplication/json
acceptapplication/json

Request Body​

{
"template": {
"jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
"writing_guidelines": {
"global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
"chapters": [
{
"guide": "本章節作為整份報告的摘要。",
"slot_map": [
{
"name": "company_name",
"description": "填入報告對象的公司名稱。",
"style": "純文字,不含額外標籤。"
}
]
}
]
}
},
"fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
"expert_model": "gemini-3.1-pro",
"metadata": {
"department": "finance"
},
"webhook_url": "https://example.com/webhooks/report"
}

欄位說明​

欄位型別必填說明
templateobject是報告模板內容,包含 jinja_html 與 writing_guidelines
template.jinja_htmlstring是模板的 Jinja HTML 框架
template.writing_guidelinesobject否模板的撰寫指引
fileset_idsarray of string是作為資料來源的 Fileset ID(UUID)列表,知識庫檢索只會在這些範圍內進行
promptstring是本次報告的任務描述,例如報告期間、關注重點或特定需求。系統會依此與撰寫指引決定各章節的資料檢索方向與撰寫內容。請務必提供非空白的內容
expert_modelstring否指定章節撰寫與章節整合階段使用的模型,未提供時採用系統預設模型。資料檢索與模板填充階段不受此設定影響。可用模型可由「取得所有模型」API 查詢
metadataobject否自訂附加資訊(Key-Value)
webhook_urlstring (URL)否接收非同步處理通知的 Webhook URL,需為合法的 HTTP / HTTPS URL
idstring (uuid)否指定報告 ID,用於重新執行失敗的報告,詳見下方說明

writing_guidelines 的結構需與報告模板 API 產出的格式一致,即包含 global_guide 與 chapters 兩個頂層欄位,詳見「建立報告模板」章節的「writing_guidelines 結構」。chapters 的順序即為系統生成章節的順序,chapters[].slot_map 決定套版階段會填入哪些 slot。若 chapters 為空,系統沒有可生成的章節,報告會轉為 failed。
expert_model 會一併寫入回應的 metadata.expert_model。


撰寫指引對生成結果的影響​

系統完全依據 writing_guidelines 決定報告的章節結構與各章節內容,因此撰寫指引的品質會直接影響生成結果。如需調整,建議先透過「更新報告模板」API 修改模板的撰寫指引,再重新取得並帶入建立報告的請求。

欄位對生成結果的影響
global_guide所有章節共用的最高層級規範,影響資料檢索、章節撰寫與章節整合
chapters陣列長度即為報告的章節數量,順序即為生成與呈現的順序
chapters[].guide單一章節的撰寫任務說明,同時決定該章節檢索資料的方向
chapters[].slot_map決定該章節在套版階段會填入哪些 slot
slot_map[].description資料檢索與內容撰寫時的重要依據
slot_map[].style章節內容與 slot 值的輸出格式依據,決定內容為 HTML 結構或純文字

各章節會獨立生成、彼此不共用上下文;所有章節完成後,系統會再統一整合全部章節,處理術語一致、段落銜接與 HTML 結構。整合不會新增或刪除章節,也不負責事實查核或內容審查。生成內容僅來自指定 Fileset 的檢索結果,知識庫缺乏相關資料時,章節內容可能不完整。章節內容目前不支援圖片(<img>)。


重新執行失敗的報告​

若帶入 id:

  • 該 ID 的報告已存在且狀態為 failed 時,系統會以本次請求的內容覆寫,並重新執行生成流程。重新執行時 draft、rendered_html 與匯出檔案 ID 都會被清除,狀態重設為 generating_draft;fail_detail 會保留先前的失敗紀錄。

  • 該 ID 的報告已存在且狀態為其他值時,回傳 409(REPORT_GENERATION_004),不會覆寫既有資料。

  • 該 ID 的報告不存在時,系統會以該 ID 建立新報告。


cURL 範例​

curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"template": {
"jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
"writing_guidelines": {
"global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
"chapters": [
{
"guide": "本章節作為整份報告的摘要。",
"slot_map": [
{
"name": "company_name",
"description": "填入報告對象的公司名稱。",
"style": "純文字,不含額外標籤。"
}
]
}
]
}
},
"fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
"webhook_url": "https://example.com/webhooks/report"
}'

Response 範例​

{
"object": "report",
"id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
"metadata": {
"department": "finance",
"expert_model": "gemini-3.1-pro"
},
"state": "generating_draft",
"fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
"exports": {
"pdf_file_id": null,
"docx_file_id": null
},
"fail_detail": [],
"webhook_url": "https://example.com/webhooks/report",
"template": {
"jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
"writing_guidelines": {
"global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
"chapters": ["..."]
}
},
"draft": null,
"rendered_html": null
}

建立報告的回應會包含本次帶入的 template;draft 與 rendered_html 尚未產生,以 null 回傳。

Response 欄位​

欄位型別說明
objectstring資源類型,固定為 report
idstring (uuid)報告 ID
metadataobject報告附加資訊,包含 expert_model
statestring報告目前的處理狀態,請參考下方「報告狀態」
fileset_idsarray of string本報告使用的 Fileset ID 列表
promptstring | null本報告的任務描述
exportsobject已匯出檔案的 ID,包含 pdf_file_id 與 docx_file_id
fail_detailarray失敗紀錄,無失敗時為空陣列
webhook_urlstring | null接收通知的 Webhook URL
templateobject | null報告使用的模板內容;取得報告 API 需透過 expand 取得
draftobject | null章節草稿內容;取得報告 API 需透過 expand 取得
rendered_htmlstring | null套版完成的完整 HTML;取得報告 API 需透過 expand 取得

報告 API 的回應一律包含上表所有欄位;未展開或尚未產生的欄位以 null 回傳,而非從回應中移除。
後續查詢、確認、匯出或刪除報告時,請使用回應中的 id 作為 report_id。


2. 取得報告​

取得指定報告的目前狀態與資料。

Endpoint​

GET /beta/report-generation/reports/{report_id}

Path Parameters​

參數型別必填說明
report_idstring (uuid)是報告 ID,非合法 UUID 時回傳 422

Query Parameters​

expand​

expand 用於額外取得報告內容。

參數型別必填說明
expandarray of string否指定要展開的欄位

支援的欄位包括:

欄位說明
template建立報告時帶入的模板內容
draft各章節的草稿內容與引用來源
rendered_html套版完成後的完整 HTML

多個欄位可使用逗號分隔:

GET /beta/report-generation/reports/{report_id}?expand=template,draft,rendered_html

也可以重複傳入:

GET /beta/report-generation/reports/{report_id}?expand=draft&expand=rendered_html

指定不支援的欄位時,API 會回傳 400(REPORT_GENERATION_006),並在 fields 中列出不支援的欄位。


cURL 範例​

curl -X GET 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70?expand=draft' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"

Response 範例​

{
"object": "report",
"id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
"metadata": {
"department": "finance",
"expert_model": "gemini-3.1-pro"
},
"state": "pending_review",
"fileset_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"prompt": "請針對 2026 年第二季的營運狀況撰寫報告。",
"exports": {
"pdf_file_id": null,
"docx_file_id": null
},
"fail_detail": [],
"webhook_url": "https://example.com/webhooks/report",
"template": null,
"draft": {
"chapters": [
{
"chapter_id": 0,
"state": "completed",
"content": "<p>本季整體營收較前一季成長 12%。</p>",
"references": [
{
"chunk_id": "d2f1a8c0-1b3e-4c5d-9a7b-6e8f0a1b2c3d",
"metadata": {
"file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"filename": "2026Q2_financial.pdf"
},
"page_content": "2026 年第二季合併營收為新台幣 ..."
}
]
}
]
},
"rendered_html": null
}

報告仍在處理中時,尚未產生的欄位會以 null 回傳。


3. 確認報告草稿​

確認系統生成的章節草稿,並啟動模板填充程序。

Endpoint​

POST /beta/report-generation/reports/{report_id}/confirm

此 API 可在報告狀態為以下值時呼叫,其他狀態會回傳 409(REPORT_GENERATION_004):

pending_review
failed

允許在 failed 狀態下呼叫,是為了讓使用者以修正後的內容重新套版。報告尚未產生任何草稿內容時(例如草稿生成階段就失敗),呼叫此 API 會回傳 409(REPORT_GENERATION_007),請改以「重新執行失敗的報告」方式重新建立。
確認前,請先取得草稿內容:

GET /beta/report-generation/reports/{report_id}?expand=draft

Request Body​

{
"chapters": [
{
"chapter_id": 0,
"content": "<p>本季整體營收較前一季成長 12%。</p>"
},
{
"chapter_id": 1,
"content": "<p>主要成長動能來自海外市場。</p>"
}
]
}

欄位說明​

欄位型別必填說明
chaptersarray是確認後的章節內容列表
chapters[].chapter_idinteger是章節編號,對應 draft.chapters 中的章節
chapters[].contentstring是確認或修改後的章節內容

Request Body 不接受上表以外的頂層欄位,帶入未定義的欄位會回傳 422。

  • chapters 會完整取代原有的草稿內容。未包含在請求中的章節不會被保留,也不會參與後續套版,因此請帶入所有需要出現在報告中的章節。

  • 各章節的 state 與 references 由系統沿用原草稿的值,不需在請求中提供。

  • chapter_id 必須是目前草稿中存在的章節編號。建議依 chapter_id 由小到大送出草稿中的全部章節。

  • 草稿中 state 為 failed 的章節,可直接以人工撰寫的內容取代後送出。

確認後,系統會依各章節在撰寫指引中的 slot_map,將章節內容拆解為各 slot 的值並填入模板:

  • slot 的值只會從章節內容中擷取或改寫,不會加入章節中沒有的資訊,因此請將需要出現在報告中的內容完整寫入對應章節。

  • slot 的值會依該 slot 的 style 輸出 HTML,且套入模板時不會做 HTML 跳脫,值中的 HTML 會直接生效。

  • 模板中未被任何章節填入的 slot 會渲染為空白,不會產生錯誤。


cURL 範例​

curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70/confirm' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"chapters": [
{
"chapter_id": 0,
"content": "<p>本季整體營收較前一季成長 12%。</p>"
}
]
}'

確認成功後回傳 202 Accepted,回應內容為更新後的報告(包含 template 與更新後的 draft),處理期間報告會進入:

filling_template

完成後則轉為:

completed

套版失敗時則轉為 failed。兩種情況都會發送 Webhook 通知(若有設定 webhook_url)。


4. 匯出報告​

將完成的報告匯出為檔案。

Endpoint​

POST /beta/report-generation/reports/{report_id}/export

此 API 僅適用於狀態為以下值的報告,其他狀態會回傳 409(REPORT_GENERATION_004):

completed

匯出為同步處理,API 會在 PDF 產生完成後才回應。


Query Parameters​

參數型別必填說明
formatstring否匯出格式,目前僅支援 pdf,其他值會回傳 422

同一份報告以相同格式重複呼叫時,會回傳先前已產生的檔案,不會重新生成。


cURL 範例​

curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70/export?format=pdf' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"

Response 範例​

{
"object": "file",
"id": "b7c4e2a1-9d8f-4a3b-8c2d-1e0f9a8b7c6d",
"filename": "report_8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70.pdf",
"filetype": "application/pdf",
"bytes": 482913,
"metadata": {
"report_id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
"export_format": "pdf"
},
"purpose": "report_export",
"created_at": "2026-10-08T08:10:00.123456Z",
"expires_at": null
}

Response 欄位​

欄位型別說明
objectstring資源類型,固定為 file
idstring (uuid)檔案 ID,可透過「下載檔案」API 下載
filenamestring檔案名稱,格式為 report_{report_id}.pdf
filetypestring檔案的 MIME 類型
bytesinteger檔案大小(位元組)
metadataobject檔案附加資訊,包含來源報告 ID 與匯出格式
purposestring檔案用途,匯出報告固定為 report_export
created_atstring (date-time)檔案建立時間
expires_atstring | null檔案到期時間

匯出後的檔案 ID 也會寫入報告的 exports.pdf_file_id,可在取得報告時一併查看。匯出檔案的結構與其他檔案相同,詳見「檔案物件」章節。


5. 刪除報告​

刪除一份報告。

Endpoint​

DELETE /beta/report-generation/reports/{report_id}

刪除後資料無法復原。報告處於任何狀態都可以刪除,包含處理中的報告。


cURL 範例​

curl -X DELETE 'https://api.bcm.apmic.ai/beta/report-generation/reports/8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"

Response 範例​

{
"id": "8a1c1f5e-2f7a-4f0b-9e1b-2d3c4b5a6f70",
"object": "report",
"deleted": true
}

報告不存在或不屬於目前的 API Key 時,回傳 404(REPORT_GENERATION_001)。
已匯出的 PDF 檔案不會隨報告一併刪除,如需移除請另行透過「刪除單一檔案」API 處理。


報告狀態​

狀態說明建議操作
generating_draft系統正在逐章節檢索資料並生成草稿等待 Webhook 通知或查詢最新狀態
pending_review草稿已生成完成取得 draft 並確認或修改章節內容
filling_template系統正在將章節內容填入模板等待 Webhook 通知或查詢最新狀態
completed報告生成完成取得 rendered_html 或匯出 PDF
failed報告處理失敗檢查 fail_detail:草稿已產生時可重新確認草稿;否則以相同 id 重新建立報告

狀態流轉如下:

generating_draft ──(草稿生成失敗)──→ failed ──(帶 id 重新建立)──→ generating_draft
↓
pending_review
↓ 呼叫確認 API
filling_template ──(套版失敗)──→ failed ──(重新確認草稿)──→ filling_template
↓
completed

報告主要欄位​

template​

建立報告時帶入的模板內容,報告建立後即固定,不會隨原始模板的後續修改而變動。

{
"jinja_html": "<html><body><h1>{{ company_name }}</h1></body></html>",
"writing_guidelines": {
"global_guide": "本報告應以正式、客觀且資料導向的語氣撰寫。",
"chapters": []
}
}

draft​

各章節的草稿內容。chapters 的順序與編號對應模板 writing_guidelines.chapters 的順序。

{
"chapters": [
{
"chapter_id": 0,
"state": "completed",
"content": "<p>本季整體營收較前一季成長 12%。</p>",
"references": []
}
]
}
欄位型別說明
chapter_idinteger章節編號,自 0 起算
statestring該章節的生成結果,completed 或 failed
contentstring章節內容,通常為 HTML 片段
referencesarray該章節生成時檢索到的知識庫片段,每筆包含 chunk_id、metadata(來源資訊,例如 file_id 與 filename)與 page_content(片段原文)

references 記錄的是該章節生成時檢索到的資料片段,可用於追溯內容來源;但不代表章節內容與片段逐句對應,仍需人工檢視確認。
個別章節生成失敗時,系統會自動重試;仍失敗時,該章節的 state 會是 failed,內容為失敗提示(<p>本章生成失敗</p>),但整份報告仍會進入 pending_review,可在確認草稿時自行補上內容。若所有章節皆生成失敗,或章節整合失敗,整份報告會轉為 failed,fail_detail 記錄 failed_step 為 generate_report。

rendered_html​

套版完成後的完整 HTML,可直接於瀏覽器開啟檢視,也是匯出 PDF 的來源。

exports​

已匯出檔案的 ID。目前僅支援匯出 PDF。

{
"pdf_file_id": "b7c4e2a1-9d8f-4a3b-8c2d-1e0f9a8b7c6d",
"docx_file_id": null
}

fail_detail​

失敗紀錄陣列,每次失敗會累加一筆。

[
{
"error": "...",
"failed_step": "generate_report"
}
]
failed_step說明
enqueue建立報告後排入生成佇列失敗(建立報告 API 會同時回傳錯誤)
generate_report草稿生成或章節整合階段失敗
fill_template模板填充階段失敗
redelivered_message生成任務被重新投遞後中止,需以相同 id 重新建立報告

error 為錯誤訊息文字。


Webhook​

建立報告時,可透過 webhook_url 指定接收非同步處理通知的 URL。系統只會在以下時間點發送通知:

時間點通知時的 state
草稿生成完成pending_review
套版完成completed
任一非同步階段失敗(草稿生成、套版、任務重新投遞)failed

建立報告(generating_draft)與呼叫確認草稿 API(filling_template)時的狀態變更不會發送通知,因為這兩個狀態會直接由 API 回應帶出。排入佇列失敗(failed_step 為 enqueue)時,建立報告 API 會直接回傳錯誤,也不會發送通知。
Webhook 以 POST 發送 application/json,內容為完整的報告資料,欄位與取得報告 API 的回應一致,並且一律包含 template、draft 與 rendered_html,不受 expand 影響。
Webhook 目前只會發送一次,接收端回應失敗或逾時時系統不會重送。收到通知後,建議再呼叫 GET API 確認最新報告狀態;若未收到通知,請以 GET API 輪詢狀態。


錯誤處理​

當 Request Body、Path Parameter 或 Query Parameter 不符合 API Schema 時,API 會回傳 422:

{
"detail": [
{
"loc": ["body", "template"],
"msg": "Field required",
"type": "missing"
}
]
}

其餘錯誤會以下列格式回傳:

{
"error_code": "REPORT_GENERATION_004",
"error_message": "Report is in completed state, expected pending_review. Please refer to the API documentation.",
"state": "completed",
"expected_state": "pending_review"
}
HTTPerror_code說明
401AUTH_001未提供 Authorization header
403AUTH_002 / AUTH_003API Key 無效或已過期
404REPORT_GENERATION_001報告不存在,或不屬於目前的 API Key,附 report_id
409REPORT_GENERATION_004報告目前狀態不允許此操作,附 state 與 expected_state
409REPORT_GENERATION_007報告尚未產生草稿內容,無法確認,附 report_id
400REPORT_GENERATION_006expand 指定了不支援的欄位,附 fields
422—Request Body 或參數不符合 Schema

草稿生成與章節整合等背景流程中的錯誤,不會直接由 API 回傳,而是讓報告轉為 failed 並記錄於 fail_detail。完整錯誤代碼請參考 錯誤代碼說明-報告生成。


串接注意事項​

項目說明
API 路徑Report Generation API 目前使用 /beta,屬預覽版功能,不保證向下相容
模板帶入方式建立報告時需帶入完整的 template 物件,而非 template_id
模板快照報告會保留建立當下的模板內容,原始模板之後的修改不會影響既有報告
非同步處理建立與確認報告後,需依 state 判斷處理進度
Report IDPath Parameter 使用 report_id,需為合法的 UUID
Expand可使用逗號分隔或重複傳入,支援 template / draft / rendered_html
Null 處理未展開或尚未產生的欄位會以 null 回傳
章節取代確認草稿時送出的 chapters 會完整取代原有草稿
失敗章節個別章節失敗不會中斷整份報告,可在確認草稿時以人工內容補上
引用來源references 僅記錄檢索到的片段,不代表內容逐句對應,仍需人工檢視
模型選擇expert_model 影響章節撰寫與章節整合階段
匯出限制匯出僅適用於 completed 狀態,且目前僅支援 PDF
重複匯出同一格式重複匯出會回傳既有檔案,不會重新生成
重新執行限制帶 id 重新執行僅適用於 failed 狀態的報告
資料範圍報告僅能由建立它的 API Key 查詢、確認、匯出與刪除,詳見「Tenant Scope 與資料隔離」章節
Webhook僅在 pending_review、completed、failed 時發送且不重送,收到通知後建議再呼叫 GET API 確認最新狀態