報告生成
Beta 預覽版
Report Generation API 目前位於 /beta 路徑下,屬於預覽版功能。API 介面、欄位、處理行為及回應格式可能隨產品迭代調整(包含但不限於變更規格、移除功能),APMIC 不保證其向下相容性。
報告用於根據已建立完成的報告模板與指定的知識版本(Fileset),自動產生一份完整報告。系統會依照模板的撰寫指引逐章節檢索資料並生成內容,經使用者確認後套回模板版面,最後可匯出為 PDF。
系統會依序完成以下處理:
-
草稿生成:依照模板的
writing_guidelines,逐章節執行知識庫檢索與內容撰寫,產生draft。 -
草稿確認:由使用者檢視或修改各章節內容後回傳,作為套版依據。
-
模板填充:將確認後的章節內容拆解為模板的各個 slot,並渲染為完整的
rendered_html。 -
報告匯出:將完成的報告轉換為 PDF 檔案,並透過 Files API 取得檔案。
建立報告前,請先完成報告模板(狀態為 completed,詳見「建立報告模板」章節),並準備好要作為資料來源的 Fileset。
API 一覽
| 功能 | Method | Endpoint |
|---|---|---|
| 建立報告 | 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
| Header | Value |
|---|---|
Authorization | Bearer <your-api-key> |
Content-Type | application/json |
accept | application/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"
}
欄位說明
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
template | object | 是 | 報告模板內容,包含 jinja_html 與 writing_guidelines |
template.jinja_html | string | 是 | 模板的 Jinja HTML 框架 |
template.writing_guidelines | object | 否 | 模板的撰寫指引 |
fileset_ids | array of string | 是 | 作為資料來源的 Fileset ID(UUID)列表,知識庫檢索只會在這些範圍內進行 |
prompt | string | 是 | 本次報告的任務描述,例如報告期間、關注重點或特定需求。系統會依此與撰寫指引決定各章節的資料檢索方向與撰寫內容。請務必提供非空白的內容 |
expert_model | string | 否 | 指定章節撰寫與章節整合階段使用的模型,未提供時採用系統預設模型。資料檢索與模板填充階段不受此設定影響。可用模型可由「取得所有模型」API 查詢 |
metadata | object | 否 | 自訂附加資訊(Key-Value) |
webhook_url | string (URL) | 否 | 接收非同步處理通知的 Webhook URL,需為合法的 HTTP / HTTPS URL |
id | string (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 欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
object | string | 資源類型,固定為 report |
id | string (uuid) | 報告 ID |
metadata | object | 報告附加資訊,包含 expert_model |
state | string | 報告目前的處理狀態,請參考下方「報告狀態」 |
fileset_ids | array of string | 本報告使用的 Fileset ID 列表 |
prompt | string | null | 本報告的任務描述 |
exports | object | 已匯出檔案的 ID,包含 pdf_file_id 與 docx_file_id |
fail_detail | array | 失敗紀錄,無失敗時為空陣列 |
webhook_url | string | null | 接收通知的 Webhook URL |
template | object | null | 報告使用的模板內容;取得報告 API 需透過 expand 取得 |
draft | object | null | 章節草稿內容;取得報告 API 需透過 expand 取得 |
rendered_html | string | null | 套版完成的完整 HTML;取得報告 API 需透過 expand 取得 |
報告 API 的回應一律包含上表所有欄位;未展開或尚未產生的欄位以 null 回傳,而非從回應中移除。
後續查詢、確認、匯出或刪除報告時,請使用回應中的 id 作為 report_id。
2. 取得報告
取得指定報告的目前狀態與資料。
Endpoint
GET /beta/report-generation/reports/{report_id}
Path Parameters
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
report_id | string (uuid) | 是 | 報告 ID,非合法 UUID 時回傳 422 |
Query Parameters
expand
expand 用於額外取得報告內容。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
expand | array 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>"
}
]
}
欄位說明
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
chapters | array | 是 | 確認後的章節內容列表 |
chapters[].chapter_id | integer | 是 | 章節編號,對應 draft.chapters 中的章節 |
chapters[].content | string | 是 | 確認或修改後的章節內容 |
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
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
format | string | 否 | 匯出格式,目前僅支援 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 欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
object | string | 資源類型,固定為 file |
id | string (uuid) | 檔案 ID,可透過「下載檔案」API 下載 |
filename | string | 檔案名稱,格式為 report_{report_id}.pdf |
filetype | string | 檔案的 MIME 類型 |
bytes | integer | 檔案大小(位元組) |
metadata | object | 檔案附加資訊,包含來源報告 ID 與匯出格式 |
purpose | string | 檔案用途,匯出報告固定為 report_export |
created_at | string (date-time) | 檔案建立時間 |
expires_at | string | 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_id | integer | 章節編號,自 0 起算 |
state | string | 該章節的生成結果,completed 或 failed |
content | string | 章節內容,通常為 HTML 片段 |
references | array | 該章節生成時檢索到的知識庫片段,每筆包含 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"
}
| HTTP | error_code | 說明 |
|---|---|---|
401 | AUTH_001 | 未提供 Authorization header |
403 | AUTH_002 / AUTH_003 | API Key 無效或已過期 |
404 | REPORT_GENERATION_001 | 報告不存在,或不屬於目前的 API Key,附 report_id |
409 | REPORT_GENERATION_004 | 報告目前狀態不允許此操作,附 state 與 expected_state |
409 | REPORT_GENERATION_007 | 報告尚未產生草稿內容,無法確認,附 report_id |
400 | REPORT_GENERATION_006 | expand 指定了不支援的欄位,附 fields |
422 | — | Request Body 或參數不符合 Schema |
草稿生成與章節整合等背景流程中的錯誤,不會直接由 API 回傳,而是讓報告轉為 failed 並記錄於 fail_detail。完整錯誤代碼請參考 錯誤代碼說明-報告生成。
串接注意事項
| 項目 | 說明 |
|---|---|
| API 路徑 | Report Generation API 目前使用 /beta,屬預覽版功能,不保證向下相容 |
| 模板帶入方式 | 建立報告時需帶入完整的 template 物件,而非 template_id |
| 模板快照 | 報告會保留建立當下的模板內容,原始模板之後的修改不會影響既有報告 |
| 非同步處理 | 建立與確認報告後,需依 state 判斷處理進度 |
| Report ID | Path 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 確認最新狀態 |