01 · 90 秒上手
快速開始
建一把金鑰、把客戶端指向 hypereal.build,即可上線。驗證與請求格式都與 OpenAI 相容 — 多數 SDK 只要更換 base URL 就能直接使用。
至少儲值 $2(200 額度),於下列頁面建立金鑰 /manage-api-keys。金鑰開頭為 ck_。
Base URL: https://hypereal.build/api/v1
驗證標頭為 Authorization: Bearer ck_...。沿用你已熟悉的 OpenAI 請求格式即可。
curl https://hypereal.build/api/v1/chat/completions \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "Say hi in one word."}]
}'import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.NEOCLOUD_API_KEY, // ck_...
baseURL: 'https://hypereal.build/api/v1',
});
const completion = await client.chat.completions.create({
model: 'gpt-5.5',
messages: [{ role: 'user', content: 'Say hi in one word.' }],
});
console.log(completion.choices[0].message.content);02
驗證
每次請求都需要一把 ck_ 開頭的金鑰。我們接受三種標頭格式,涵蓋所有 SDK。
Bearer ck_... — OpenAI SDK、Codex CLI 與 Cursor 使用此格式。ck_... — Anthropic SDK 與 Claude Code 在 /v1/messages上使用。ck_... — Google Gemini SDK / 原生格式, /v1/gemini.?key=ck_... 也可使用。03 · OpenAI 相容
Chat Completions
主力端點。沿用 OpenAI Chat Completions 連線格式。適用於 GPT、Gemini、Qwen、DeepSeek、GLM,以及所有非 Anthropic 的 LLM。
/api/v1/chat/completions請求內容
/v1/messages 。role、 content)。false。設為 true時走 SSE 串流;最終 chunk 會包含用量資訊。計價
依各模型的輸入 / 輸出費率按 token 計費。100 額度 = $1.00。呼叫此端點所需的最低餘額為 200 額度($2.00)。
curl https://hypereal.build/api/v1/chat/completions \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [
{"role": "system", "content": "You are a terse assistant."},
{"role": "user", "content": "Two-line haiku about caches."}
],
"stream": true,
"max_tokens": 256
}'import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.NEOCLOUD_API_KEY,
baseURL: 'https://hypereal.build/api/v1',
});
const stream = await client.chat.completions.create({
model: 'gpt-5.5',
stream: true,
messages: [{ role: 'user', content: 'Stream me a haiku.' }],
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}OpenAI 與相容供應商模型
gpt-5gpt-5.1gpt-5.2gpt-5.3gpt-5.4gpt-5.5gpt-5.5-instantgpt-5.5-progpt-5.4-minigpt-5.4-nanogpt-5.4-officialgpt-5.4-pro-officialgpt-5.2-officialgpt-5-pro-officialgpt-realtime-1.5-officialgpt-audio-1.5-officialglm-5qwen3.5-plusqwen3.5-flashqwen3-maxdeepseek-v3.2kimi-k2.5MiniMax-M2.5nano-banana-204 · Anthropic 相容
Messages
Anthropic /v1/messages 連線格式,支援 extended thinking、多上游故障轉移,以及 15 秒 SSE keepalive。Claude Code、OpenCode、OpenClaw 與官方 Anthropic SDK 皆可使用。
/api/v1/messages請求內容
claude-opus-4-6, claude-sonnet-4-6, 或 claude-haiku-4-5。較舊的 Anthropic ID(claude-sonnet-4-5-20250929, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022)會自動別名到對應的最新版本。budget_tokens 限制 reasoning trace 上限。端點每 15 秒送出 SSE ping,避免代理伺服器在 thinking 串流過久時中斷連線。curl https://hypereal.build/api/v1/messages \
-H "x-api-key: ck_..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Plan a 3-step refactor of a Next.js app."}
],
"thinking": {"type": "enabled", "budget_tokens": 4000}
}'import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.NEOCLOUD_API_KEY, // ck_...
baseURL: 'https://hypereal.build/api/v1',
});
const msg = await client.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello, Claude.' }],
});
console.log(msg.content);Anthropic 模型
claude-opus-4-6claude-sonnet-4-6claude-haiku-4-505 · OpenAI Responses API
Responses
OpenAI 較新的 Responses API(Codex CLI 的 `wire_api = responses` 模式與 OpenAI Agents SDK 都使用)。驗證方式與 chat/completions 相同;請求內容以 `input` 取代 `messages`。
/api/v1/responses備註
- Anthropic 模型會回傳 400 — 它們屬於
/v1/messages。 - 串流與非串流皆依
response.usage.input_tokens/output_tokens計費。 - 部分上游一律回 SSE — 端點會自動偵測並透明串流回客戶端,即使你設定
stream:false也是如此。 - 支援多上游故障轉移。請將客戶端 timeout 設長(300 秒以上)。
curl https://hypereal.build/api/v1/responses \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.1-codex",
"input": "Write a TypeScript function that debounces a callback.",
"stream": true
}'import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.NEOCLOUD_API_KEY,
baseURL: 'https://hypereal.build/api/v1',
});
const response = await client.responses.create({
model: 'gpt-5-codex',
input: 'Refactor this file into smaller modules.',
});
console.log(response.output_text);Codex 調校過的模型
gpt-5-codexgpt-5-codex-minigpt-5.1-codexgpt-5.1-codex-minigpt-5.1-codex-maxgpt-5.2-codexgpt-5.3-codexgpt-5.3-codex-sparkgpt-5.3-codex-official06 · Codex CLI / Codex Desktop
Codex CLI
Codex 將 `wire_api = responses` 供應商指向 /api/v1/codex/responses。CLI 會在 base URL 後自動補上 `/responses`,因此請依下方方式設定 base URL。
/api/v1/codex/responses# ~/.codex/config.toml model_provider = "hypereal" model = "gpt-5-codex" [model_providers.hypereal] name = "Hypereal" base_url = "https://hypereal.build/api/v1/codex" wire_api = "responses" env_key = "NEOCLOUD_API_KEY"
接著匯出你的金鑰:export NEOCLOUD_API_KEY=ck_...
照常執行 codex 。Codex 送出的所有內容 — 完整 reasoning 串流、tool calls、檔案編輯 — 都會原封不動被代理。計費依標準的 input_tokens / output_tokens 用量區塊。
同樣的設定也適用於 OpenCode、Claude Code(用 /v1/messages)、Cursor(用 /v1/chat/completions),以及 Gemini CLI(用 /v1/gemini)。
07
圖像生成
OpenAI 相容的 /images/generations 格式。同步呼叫 — 上游完成時,端點會回傳圖片 URL(或 base64)。按張計費;`n` 限制在 1–10 之間。
/api/v1/images/generations請求內容
image、 reference_images)。1024x1024、 1536x1024。實際支援值取決於供應商。creditsPerGeneration × n,端點會回傳 402。curl https://hypereal.build/api/v1/images/generations \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "nano_banana_pro",
"prompt": "isometric studio shot of a tiny cyberpunk apartment, neon rim light",
"n": 1,
"size": "1024x1024"
}'const res = await fetch('https://hypereal.build/api/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.NEOCLOUD_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: 'a chrome teapot floating over the ocean at sunset',
n: 1,
}),
});
const { data } = await res.json();
console.log(data[0].url); // or data[0].b64_json depending on the model圖像模型
gpt-image-2gpt-4o-imagenano_banananano_banana_2gemini-3.1-flash-image-previewgemini-2.5-flash-image-previewflux-kontext-proflux-2-prodoubao-seedream-4-0doubao-seedream-4-5doubao-seedream-5-0gemini-3.1-flash-image-preview-officialflux-kontext-maxgemini-2.5-flash-image-officialnano_banana_progemini-3-pro-image-previewflux-2-flexgemini-3-pro-image-preview-officialgemini-3-pro-image-preview-4Kgemini-3.1-fast-imagengemini-3.1-thinking-imagen08 · 長時間任務
影片生成
同步 long-poll 端點 — 請保持連線開啟,直到影片完成。請將 HTTP 客戶端 timeout 設為 600 秒。多數模型按秒計費,Veo、Vidu、Grok 則按支計費。
/api/v1/video/generations請求內容
per_second 。16:9、 9:16、 1:1。實際支援值取決於供應商。last_image_url 或 image — 詳見該模型的上游文件。curl https://hypereal.build/api/v1/video/generations \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0",
"prompt": "drone shot flying over a foggy forest at dawn, cinematic",
"duration": 5,
"aspect_ratio": "16:9",
"image_url": "https://example.com/keyframe.jpg"
}'const res = await fetch('https://hypereal.build/api/v1/video/generations', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.NEOCLOUD_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'kling-v3',
prompt: 'a cat walking on the moon',
duration: 5,
aspect_ratio: '16:9',
}),
});
// Long-running: connection stays open until the upstream returns the clip.
// Set a generous timeout (300+ seconds).
const data = await res.json();
console.log(data); // contains url(s) to the rendered mp4影片模型
wan2.6-flashkling-2-6MiniMax-Hailuo-02doubao-seedance-1-0-pro-fastMiniMax-Hailuo-2.3wan2.6kling-video-o1kling-v3-omnikling-v3kling-v3-videodoubao-seedance-1-0-pro-qualitydoubao-seedance-2-0doubao-seedance-2-0-fastdoubao-seedance-1-5-proVeo3.1-fast-officialVeo3.1-quality-officialveo3.1-fastveo3.1-qualityvidu-q3-progrok-video-309 · Fish Audio
音訊 — TTS、聲音複製、ASR
三個模型 ID 共用同一個端點,請求與回應格式取決於你呼叫哪一個。供應商為 Fish Audio(直連,不經 ToAPI),按次計費。
/api/v1/audio/generationsaudio-tts 與 audio-clone。audio-asr (輸入)與 audio-clone (參考音檔,需 ≥ 10 秒)。data: [{ url }] 用於 TTS / 聲音複製, text (可附加 segments、 duration)用於 ASR。curl https://hypereal.build/api/v1/audio/generations \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "audio-tts",
"text": "Welcome to Hypereal. One key, every model.",
"voice_id": "en_male_calm"
}'curl https://hypereal.build/api/v1/audio/generations \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "audio-clone",
"text": "This is my cloned voice.",
"audio": "https://example.com/reference-30s.mp3"
}'curl https://hypereal.build/api/v1/audio/generations \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "audio-asr",
"audio": "https://example.com/recording.mp3"
}'音訊模型
audio-ttsaudio-cloneaudio-asr10 · Google 原生格式
Gemini
同一端點同時接受 Gemini 原生格式(`contents` / `generationConfig` / `systemInstruction`)與 OpenAI 格式。端點會在內部先轉成 OpenAI 格式再轉發。多數情況下,直接用 /v1/chat/completions 搭配 Gemini 模型 ID 更簡單。
/api/v1/geminitemperature、 maxOutputTokens 等。contents。驗證標頭: x-goog-api-key: ck_...、 ?key=ck_...,或 Authorization: Bearer ck_... 都可使用。
curl "https://hypereal.build/api/v1/gemini" \
-H "x-goog-api-key: ck_..." \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-pro",
"contents": [
{"role": "user", "parts": [{"text": "Outline a launch plan."}]}
],
"generationConfig": {"temperature": 0.6, "maxOutputTokens": 2048}
}'// The /v1/gemini endpoint accepts both Gemini-native and OpenAI shapes.
// For SDK use, the OpenAI client + /v1/chat/completions is simpler.
const res = await fetch('https://hypereal.build/api/v1/gemini', {
method: 'POST',
headers: {
'x-goog-api-key': process.env.NEOCLOUD_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gemini-3.1-fast',
contents: [{ role: 'user', parts: [{ text: 'Hi' }] }],
}),
});
console.log(await res.json());Gemini 模型
gemini-3-pro-officialgemini-3-pro-preview-officialgemini-3-flash-officialgemini-3-flash-preview-officialgemini-3.1-progemini-3.1-pro-preview-officialgemini-3.1-fastgemini-3.1-thinkinggemini-3.1-flash-lite-preview-officialgemini-2.5-pro-officialgemini-2.5-flash-officialgemini-2.5-flash-lite-officialgemini-2.0-flash-officialgemini-2.0-flash-lite-officialgemini-2.0-flash-vipgemini-2.5-flash-vipgemini-2.5-pro-vipgemini-3-flash-preview-vip11
錯誤與頻率限制
所有錯誤都是 { error: { type, message } } 形式的 JSON。頻率限制以每位使用者為單位,而非每把金鑰 — 多把金鑰共用同一份配額。
ck_ 前綴)、過期或停用。X-RateLimit-Limit、 X-RateLimit-Remaining,以及 X-RateLimit-Reset 標頭。model、未知的模型 ID(回應會包含 available_models),或在錯誤的端點上呼叫(例如把 Anthropic 模型送到 /chat/completions)。12
計價與額度
單一單位:100 額度 = $1.00 美元。LLM 依每個模型的輸入 / 輸出費率按 token 計費;媒體模型按張、按秒或按支計費。
LLM
Tokens × 每百萬 token 費率。串流請求依最終用量 chunk 計費。
圖像
每次生成固定費率 × 實際回傳的 n 。
影片與音訊
按秒(多數影片)、按支(Veo、Vidu、Grok),或按次(Fish Audio)計費。
Claude、GPT、Gemini,以及精選圖像模型(GPT Image 2、Nano Banana)售價低於原廠。影片、音訊與其他媒體模型以標準價計費。

