API 功能指南

API功能介紹

本章節介紹六個主要 API 功能，包含Models、 Completions、Chat Completions、Embeddings、Tool Calling和Reasoning Effort，說明各 API 格式的基本結構和用途。

Models

概述

Models API 用於查看 API入口提供的模型列表和其特性。此 API 允許使用者查詢可用模型的相關資訊，適合選擇不同應用需求的模型。

請求格式

Endpoint: /v1/models

HTTP 方法: GET

範例請求 for Linux:

curl -X 'GET' "https://portal.genai.nchc.org.tw/api/v1/models" \
-H "x-api-key: <您的API KEY>" \
-H 'Content-Type: application/json'

範例請求 for windows PowerShell:

curl.exe -X GET "https://portal.genai.nchc.org.tw/api/v1/models" -H "x-api-key: 您的API_KEY" -H "Content-Type: application/json"

回應格式

data：包含模型列表，每個模型包含 id、object、created 等屬性，提供模型的詳細資訊。

Completions

概述

Completions API 用於根據輸入的提示文本（prompt）生成一段連貫文字，適用於單輪內容生成、摘要、問答、續寫等場景。

請求格式

Endpoint: /v1/completions

HTTP 方法: POST

範例請求 for Linux:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
  "model": "Llama3-TAIDE-LX-8B-Instruct-Alpha1",
  "prompt": "請寫一篇以未來城市為背景的短篇小說：",
  "max_tokens": 200,
  "temperature": 0.7
}'

範例請求 for windows PowerShell: (需要存成ps1檔才能執行以免因斷行造成的錯誤)

$body = @{
  model = "Llama-3.3-Nemotron-Super-49B-v1"
  messages = @(
    @{
      role    = "user"
      content = "請寫一篇以未來城市為背景的短篇小說："
    }
  )
  max_tokens  = 200
  temperature = 0.7
} | ConvertTo-Json -Depth 5

$headers = @{
  "x-api-key" = "您的API_KEY"
}

$res = Invoke-RestMethod `
  -Uri "https://portal.genai.nchc.org.tw/api/v1/chat/completions" `
  -Method POST `
  -Headers $headers `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

"=== text ==="
$res.choices[0].message.content

"`n=== finish_reason ==="
$res.choices[0].finish_reason

"`n=== usage ==="
if ($res.PSObject.Properties.Name -contains 'usage' -and $res.usage) {
    $res.usage
} else {
    "API 回應中沒有 usage 資訊"
}

model：指定使用的模型名稱，例如 Llama3-TAIDE-LX-8B-Instruct-Alpha1。
prompt：作為輸入的提示文本，模型將根據此文本生成回應。
temperature (可選)：控制生成內容的隨機性，範圍為 0（穩定）到 1（創意）。
max_tokens (可選)：生成回應的最大長度（以 token 為單位）。

回應格式

choices：包含生成的回應列表，每個回應包含 text 和 finish_reason 屬性。
usage：包含此次請求的 token 使用量統計。

Chat Completions

概述

Chat Completions API 用於生成對話式回應，適合聊天機器人等需要多輪對話的應用。此 API 使用模型來根據給定的對話歷史生成符合上下文的回應。

請求格式

Endpoint: /v1/chat/completions

HTTP 方法: POST

範例請求 for Linux:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "Llama3-TAIDE-LX-8B-Chat-Alpha1",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant. 你是一個樂於助人的助手。"
        },
        {
            "role": "user",
            "content": "請寫一篇小說"
        }
    ],
    "max_tokens": 20,
    "temperature": 0
}'

範例請求 for windows PowerShell: (需要存成ps1檔才能執行以免因斷行造成的錯誤)

$h=@{"x-api-key"="您的API_KEY"}

$b=@{
  model="Llama-3.3-Nemotron-Super-49B-v1"
  messages=@(
    @{role="system";content="You are a helpful assistant. 你是一個樂於助人的助手。"}
    @{role="user";  content="請寫一篇小說"}
  )
  max_tokens=1024
  temperature=0.7
} | ConvertTo-Json -Depth 5

$r=Invoke-RestMethod -Uri "https://portal.genai.nchc.org.tw/api/v1/chat/completions" `
                     -Method POST -Headers $h `
                     -ContentType "application/json; charset=utf-8" -Body $b

"=== text ==="
$r.choices[0].message.content

"`n=== finish_reason ==="
$r.choices[0].finish_reason

"`n=== usage ==="
$r.usage

model：指定使用的模型名稱。
messages：包含對話歷史的列表，每個訊息需包含 role 和 content 屬性。角色 (role) 可為 user、assistant 或 system，分別表示使用者、助理和系統指令的內容。
temperature (可選)：控制回應的隨機性。範圍通常在 0 到 1 之間，值越高回應越隨機，值越低回應越保守。
max_tokens (可選)：限制回應中的最大字數，以避免生成過長的回應。

回應格式

choices：包含生成的回應列表，每個回應包含 message 和 finish_reason 屬性。
usage：包含此次請求的 token 使用量統計，分別顯示 prompt 和 completion 的 token 數量。

Embeddings

概述

Embeddings API 用於將文本轉換成向量表示，適合語意相似度分析、推薦系統等應用。每段文本會生成一組高維向量來表示其特徵。

請求格式

Endpoint: /v1/embeddings

HTTP 方法: POST

範例請求 for Linux:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/embeddings" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "Snowflake/snowflake-arctic-embed-l-v2.0",
    "input": "你好"
}'

範例請求 for windows PowerShell: (需要存成ps1檔才能執行以免因斷行造成的錯誤)

$h = @{ "x-api-key" = "您的API_KEY" }
 
$b = @{
  model = " Multilingual-E5-Large-Instruct"
  input = "你好"
} | ConvertTo-Json -Depth 5
 
$r = Invoke-RestMethod `
  -Uri "https://portal.genai.nchc.org.tw/api/v1/embeddings" `
  -Method POST `
  -Headers $h `
  -ContentType "application/json; charset=utf-8" `
  -Body $b
 
"=== data ==="
$r.data | Select-Object index, @{Name="embedding (前10維)"; Expression={ $_.embedding[0..9] }}
 
"`n=== usage ==="
if ($r.usage) { $r.usage } else { "API 無回傳 usage 統計" }

model：指定使用的模型名稱。
input：需要轉換成向量的文本或文本列表。

回應格式

data：包含生成的向量列表，每個向量包含 index 和 embedding 屬性。
usage：包含此次請求的 token 使用量統計。

Tool Calling

概述

Tool Calling（工具調用）是讓 LLM 能夠「理解何時需要外部工具」，並且「自動呼叫適當的函式」來完成任務的能力。相比傳統 LLM 只能「猜測」或「編造」答案，Tool Calling 讓 AI 能夠: 取得即時資訊（天氣、股價、新聞）、執行實際操作（發送郵件、資料庫查詢、API 呼叫）、處理複雜任務（多步驟推理 + 工具組合）。

請求格式

Endpoint: /v1/chat/completions

HTTP 方法: POST

範例請求 for Linux:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-oss-120b",
    "messages": [
        {
            "role": "system",
            "content": "Always include the language and file name in the info string when you write code blocks."
        },
        {
            "role": "user",
            "content": "What is the weather like in Boston?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ]
}'

範例請求 for windows PowerShell: (需要存成ps1檔才能執行以免因斷行造成的錯誤)

$body = @"
{
  ""model"": ""gpt-oss-120b"",
  ""messages"": [
    { ""role"": ""system"", ""content"": ""Always include the language and file name in the info string when you write code blocks."" },
    { ""role"": ""user"", ""content"": ""What is the weather like in Boston?"" }
  ],
  ""tools"": [
    {
      ""type"": ""function"",
      ""function"": {
        ""name"": ""get_current_weather"",
        ""description"": ""Get the current weather in a given location"",
        ""parameters"": {
          ""type"": ""object"",
          ""properties"": {
            ""location"": { ""type"": ""string"" },
            ""unit"": { ""type"": ""string"", ""enum"": [""celsius"", ""fahrenheit""] }
          },
          ""required"": [""location""]
        }
      }
    }
  ]
}
"@

curl.exe -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" `
-H "Content-Type: application/json" `
-H "Authorization: Bearer <您的API_KEY>" `
-d $body

回應格式

type：固定為 "function"，表示模型要呼叫一個函式
name：模型決定要使用的工具名稱
arguments：模型產生的參數（JSON 字串），用來執行該工具type：
usage: 包含此次請求之 Token 使用量統計。

Reasoning Effort

概述

Reasoning Effort用於量化推理深度與速度，使得AI在面對複雜問題時能夠像人類一樣進行深入思考。

請求格式

Endpoint: /v1/chat/completions

HTTP 方法: POST

範例請求 for Linux:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-oss-120b",
    "temperature": 0.5,
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Solve: 24*37 + 18*29. Show only the final number." }
    ],
    "extra_body": {
      "reasoning_effort": "high"
    }
  }'

範例請求 for windows PowerShell: (需要存成ps1檔才能執行以免因斷行造成的錯誤)

$body = @"
{
  ""model"": ""gpt-oss-120b"",
  ""temperature"": 0.5,
  ""messages"": [
    { ""role"": ""system"", ""content"": ""You are a helpful assistant."" },
    { ""role"": ""user"",   ""content"": ""Solve: 24*37 + 18*29. Show only the final number."" }
  ],
  ""extra_body"": {
    ""reasoning_effort"": ""high""
  }
}
"@

curl.exe -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" `
-H "Content-Type: application/json" `
-H "Authorization: Bearer <您的API KEY >" `
-d $body

model：指定使用的模型名稱，例如 gpt-oss-120b。
messages：包含對話歷史的列表，每個訊息需包含 role 和 content 屬性。角色 (role) 可為 user、assistant 或 system，分別表示使用者、助理和系統指令的內容。
temperature（可選）：控制回應的隨機性。範圍通常在 0 到 1 之間，值越高回應越隨機，值越低回應越保守。
extra_body.reasoning_effort（可選）：控制推理強度，可設定為例如 "low"、"medium"、"high" 等值，數值越高代表模型在思考與說明上投入越多資源。

回應格式

choices：包含生成的回應列表，每個回應包含 message、finish_reason 等屬性；啟用 reasoning 時，message 內會額外包含 reasoning_content，用於呈現模型的推理過程。
usage：包含此次請求的 token 使用量統計。

注意事項

API Key：使用每個 API 需提供有效的 API Key，確保具備適當的訪問權限。
Rate Limiting：每個 API 使用可能受到頻率限制，請參考 API Portal 的限制說明。
Error Handling：若請求格式錯誤或資源不足，API 將返回錯誤代碼和訊息，請根據錯誤說明進行修正。

API功能介紹​

目錄​

Models​

概述​

請求格式​

回應格式​

Completions​

概述​

請求格式​

回應格式​

Chat Completions​

概述​

請求格式​

回應格式​

Embeddings​

概述​

請求格式​

回應格式​

Tool Calling​

概述​

請求格式​

回應格式​

Reasoning Effort​

概述​

請求格式​

回應格式​

注意事項​

API功能介紹

目錄

Models

概述

請求格式

回應格式

Completions

概述

請求格式

回應格式

Chat Completions

概述

請求格式

回應格式

Embeddings

概述

請求格式

回應格式

Tool Calling

概述

請求格式

回應格式

Reasoning Effort

概述

請求格式

回應格式

注意事項