Developer Documentation

Complete API Integration Guide

OpenAI-compatible format. Access all LLM models with a single key with detailed API integration guidance.

Security Tip

Set API_BASE_URL and API_KEY as environment variables to keep keys out of your code.

Get Your API Key

Your API key is your only credential to access all LLM models. Keep it safe and do not share.

Go to the API Key Dashboard.
Log in with your THU account.
Click "Generate New API Key".
Name your key for easier management (e.g., "Thesis Research"), and select required model permissions.
After creation, copy your key immediately. For security, the key is shown only once.

Send Your First API Request

API Base URL: Please log in to view

Set Environment Variables

macOS / Linux

export API_BASE_URL="https://api.ithu.tw/v1"
export API_KEY="YOUR_API_KEY"

Windows (PowerShell)

$env:API_BASE_URL = "https://api.ithu.tw/v1"
$env:API_KEY = "YOUR_API_KEY"

Code Examples

curl https://api.ithu.tw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [
      { "role": "system", "content": "你是一個來自東海大學的有用助理。" },
      { "role": "user", "content": "請介紹東海大學的路思義教堂。" }
    ]
  }'

import os, requests, json

API_KEY = "YOUR_API_KEY"
API_BASE_URL = "https://api.ithu.tw/v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

data = {
    "model": "gpt-oss-120b",
    "messages": [
        {"role": "system", "content": "你是一個來自東海大學的有用助理。"},
        {"role": "user", "content": "請介紹東海大學的路思義教堂。"}
    ]
}

response = requests.post(
    f"{API_BASE_URL}/chat/completions",
    headers=headers,
    data=json.dumps(data)
)

if response.status_code == 200:
    print(response.json()['choices'][0]['message']['content'])
else:
    print(f"請求失敗，狀態碼: {response.status_code}")

<?php
$apiKey = "YOUR_API_KEY";
$apiBaseUrl = "https://api.ithu.tw/v1";

$payload = [
    "model" => "gpt-oss-120b",
    "messages" => [
        ["role" => "system", "content" => "你是一個來自東海大學的有用助理。"],
        ["role" => "user", "content" => "請介紹東海大學的路思義教堂。"],
    ],
];

$ch = curl_init("{$apiBaseUrl}/chat/completions");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    echo $data['choices'][0]['message']['content'];
} else {
    echo "請求失敗，狀態碼: {$httpCode}\n";
}

const API_KEY = 'YOUR_API_KEY';
const API_BASE_URL = 'https://api.ithu.tw/v1';

async function run() {
  const res = await fetch(`${API_BASE_URL}/chat/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({
      model: 'gpt-oss-120b',
      messages: [
        { role: 'system', content: '你是一個來自東海大學的有用助理。' },
        { role: 'user', content: '請介紹東海大學的路思義教堂。' },
      ],
    }),
  });
  if (!res.ok) {
    console.error('請求失敗，狀態碼:', res.status);
    return;
  }
  const data = await res.json();
  console.log(data.choices[0].message.content);
}
run().catch(console.error);

Remember to replace YOUR_API_KEY with your own key.

Troubleshooting

401/403: Verify your API key is correct and not expired.
404/Path errors: Base URL should be https://api.ithu.tw/v1; use /chat/completions or /embeddings.
Model unavailable: Check model name spelling (e.g., gpt-oss-120b, BGE-M3).
Connection issues: Check network settings and service status.

Advanced: Build a RAG QA System

Retrieval-Augmented Generation (RAG) combines information retrieval with LLMs to answer domain-specific questions. Access all models with a single key.

1. Create Knowledge Base Embeddings

def get_embeddings(texts, model="BGE-M3"):
    response = requests.post(
        f"{API_BASE_URL}/embeddings",
        headers=headers,
        data=json.dumps({"input": texts, "model": model})
    )
    if response.status_code == 200:
        return [item['embedding'] for item in response.json()['data']]
    return None

knowledge_chunks = [
    "路思義教堂是一座位於東海大學的基督新教禮拜堂...",
    "教堂為著名建築師貝聿銘與陳其寬之作..."
]
knowledge_vectors = get_embeddings(knowledge_chunks)

2. Retrieve Relevant Information

user_question = "誰設計了路思義教堂？"
question_vector = get_embeddings([user_question])[0]
relevant_context = "教堂為著名建築師貝聿銘與陳其寬之作..."

3. Generate the Final Answer

prompt = f"""根據以下資料回答問題。資料：'{relevant_context}'。問題：'{user_question}'。答案："""
final_data = {
    "model": "gpt-oss-120b",
    "messages": [{"role": "user", "content": prompt}]
}
response = requests.post(
    f"{API_BASE_URL}/chat/completions",
    headers=headers,
    data=json.dumps(final_data)
)
print(response.json()['choices'][0]['message']['content'])