AI 網關

從您的個人應用程序中使用連接到您自己的 AirCode Ø 實例的 AI 帳戶。 提供您的實例的 Base URL,一個單獨的 應用代幣,以及一個準確的 模型 ID。 該實例調用其連接的提供商 CLI ,並通過文本的聊天完成子集和圖像的圖像子集返回答案。

Your application's backend
  → your instance URL + application token
    → a connected native provider account
      → validated answer + available usage counters

網站僅託管文檔。 API 請求直接到您的實例; aircodezero.com 不會收到您的實例地址、代碼或提示。 僅爲自己的應用程序和帳戶使用此服務。 供應商條款、訂閱訪問和配額仍然適用。

設置實例

1. 在 AI 使用中連接兼容的本地提供商帳戶。 門口 列出了安裝實例支持的帳戶模型; API-key 和 管理信貸連接被排除在外。
2. 在桌面或網頁開啟 設定 → AI gateway，在手機開啟 更多 → AI gateway。在 建立存取權 下啟用 允許私人連線。
3. 複製顯示的 Base URL。 它以 /api/ai-gateway/v1結束。
4. 在 建立權杖 中選擇 應用程式，輸入名稱，然後選擇 建立權杖。權杖只顯示一次，請立即複製。此選項允許應用程式透過 AI API 使用文字和圖片，但不能啟動跨執行個體工作階段。
5. 在您的應用程序中配置以下服務器側環境變量:

將代幣保存在後端的祕密配置中,而不是瀏覽器代碼、移動應用程序包、存儲庫、 URL 或共享對話中。 示例閱讀環境變量,而不是嵌入證書。 永遠不要在 API-key 字段中使用實例密碼或所有者登錄代碼。

該實例必須繼續運行並可從應用程序的後端訪問。 localhost 指運行該後端的計算機。 使用該實例的 HTTPS 地址進行遠程訪問,或使用您可信的本地/私人網絡連接。 網關不創造公共來源。 /models 未列出的提供商不能通過發明 ID來選擇。

身份驗證和模型發現

在每次通話中發送 Authorization: Bearer YOUR_APPLICATION_TOKEN 。 用 JSON 發送 Content-Type: application/json。 未支持查詢參數或 Cookie 身份驗證。 跨源瀏覽器呼叫不受支持;使用您的後端。

GET {BASE_URL}/models 返回具有 object: "list" 和 data 數組的對象。 每個模型都提供了一個 id展出 label, engine, engineLabel, provider, connectionLabel, efforts 和 capabilities: chat.completions 對於文本模型來說, images.generations 和 images.edits 對於圖像模型來說。 返回的 id 保持不變;它可能已經包含百分比編碼。 當帳戶、提供商訪問或安裝的模型發生變化時,該列表可能會發生變化。

對於 OpenAI兼容的應用程序的配置,請選擇 聊天完成,使用完整的 Base URL,將應用程序代幣放入其 API 鍵域 ,並複製返回的模型 ID 之一。 圖像使用下文描述的圖像子集。 需要響應、工具或不支持的採樣參數的應用程序與當前網關不兼容。

生成回覆

POST {BASE_URL}/chat/completions 接受以下字段。 未知的字段被拒絕,而不是默默地忽略。

消息只包含 role 和 content。 文本塊與新聞稿相連。 零字符被拒絕。 正常化的消息數組必須在 UTF-8 JSON的64 KiB範圍內,整個 HTTP 的體積僅限於80 KiB。 驗證的答案限於49152個JavaScript字符串代碼單元。 這些是網關限制,而不是提供商的背景窗口或輸出容量的承諾。

在每個電話中提供完整的相關對話。 若要繼續對話,請附上前一個助理的答案和下一個用戶的消息。 網關不會創建或保留對話、會話或完成歷史記錄。 代幣不允許訪問實例項目、文件、終端、會話或所有者設置。

一個正常的答案有 object: "chat.completion";閱讀從 choices[0].message.content的文本。 它還包括 id, created, 所請求的 model, 和 finish_reason: "stop"。 在 usage 中,本地計數出現,當完成足以報告時。 aircode_usage 擴展將保留會計詳細信息和不完整的估計。 缺少的計數器或價格是未知的,從來沒有零。 API-equivalent估計不是額外的訂閱費用。

流媒體

stream: true 設置爲接收 Content-Type: text/event-stream。 目前的實現使用 緩衝流量:它在提供商運行時發送初始的等待評論和 keepalive 評論,然後在驗證後發送完整的答案。 不是 流詞或代幣,因爲它們被生成。

一個成功的流體包含:

1. SSE 評論開始於 : 等待;忽略它們。
2. 一個 data: JSON chat.completion.chunk 與助手角色和完成 文本爲 choices[0].delta.content。
3. 一個帶空分裂和 finish_reason: "stop"的片段。
4. choices: [], usage (可能 null) 和 aircode_usage 當 stream_options.include_usage 是真的時。
5. data: [DONE].

一旦流量開始,失敗就會作爲一個 SSE data: 事件包含 error· 不要治療 HTTP 單身200個成功 一個失敗的流沒有成功標記就關閉了。 SSE 框架可以分成傳輸塊;使用 SDK 或 SSE 分析器,而不是將每個網絡塊作爲 JSON分析。

關閉連接會取消其活躍的請求。 撤銷一個代幣、禁用網關或停止實例也取消了匹配的工作。 沒有自動重播或複製。 長期的請求需要適當的客戶端和反向代理時間;保留程序不能超過網絡的絕對請求時間限制。

生成圖像

圖像模型列出,而實例的原始 Codex 帳戶可以使用自己的圖像工具,這需要一個包含圖像生成的 ChatGPT 計劃。 它的 id 是 codex/image-generation。 Codex 決定使用哪個圖像模型;門口不會選擇一個。

• POST {BASE_URL}/images/generations 接收 JSON 接收 model, prompt (最多爲 32000 個字符)和可選的 size, n: 1 和 response_format: "b64_json".
• POST {BASE_URL}/images/edits 使用相同字段的 multipart/form-data 和 image 或 image[]中的 1 到 4 個參考圖像。 每個必須是 PNG 或 JPEG 最多爲 4 MiB。 其他文件域,例如 mask被拒絕。

size 是 64 到 4096 像素之間的 auto 或 WIDTHxHEIGHT 。 它作爲指導傳遞給模型;響應報告了實際大小。 任何其他領域都被拒絕,而不是忽略。

curl -sS "$AIRCODE_AI_BASE_URL/images/edits" \
  -H "Authorization: Bearer $AIRCODE_AI_TOKEN" \
  -F model=codex/image-generation \
  -F "prompt=Place this product in a premium studio shot on a stone pedestal." \
  -F size=1024x1536 \
  -F image=@product.png

一個響應載有 created,一個 data[0].b64_json,一個 output_format (png, jpeg 或 webp),實際的 size 和 aircode_usage。 會計涵蓋了驅動圖像工具的代理人;提供商不報告圖像工具的成本,因此 costComplete 始終是 false。 一代通常需要一到三分鐘,通過短信通話共享下面的限制,並在客戶端斷開連接時被取消。 當模型沒有圖像響應時, 422 AI_GATEWAY_NO_IMAGE 和模型的句子,如果它給出了一個,呼叫失敗。

自動連接保存的 AirCode Ø 應用程序

一個存儲在 Apps 的應用程序運行自己的服務器,可以獲得此訪問,而無需複製代幣。 在應用程序頁面上,打開 設置 → 訪問 → AI 帳戶 並打開它。 AirCode Ø 如下:

1. 打開私人 AI 網關,如果它被關閉;
2. 重新啓動應用程序,並在每次啓動時給其服務器一個新的代幣。 自己,撤銷前一開始的代幣;
3. 設置 AIRCODE_AI_BASE_URL (實例聽取的地址上的網關), AIRCODE_AI_TOKEN和,如果可用, AIRCODE_AI_MODEL (文本模型) 和 AIRCODE_AI_IMAGE_MODEL (圖像模型)。

應用程序的發佈版本也以同樣的方式獲得了自己的代幣。 關閉 AI 帳戶會立即撤銷應用程序的代幣。 從應用程序的服務器撥打網關,並在那裏保留代幣:任何可以打開應用程序的人都可以通過它使用您的帳戶,並且它們的使用對您的計劃產生影響。

報價,代幣生命週期和錯誤

該網關允許在整個實例中進行兩次活躍的呼叫,每代幣一次活躍的呼叫,每代幣每分鐘30次接受的生成請求。 電話沒有排隊。 這些局部限制不取代供應商配額。 代幣在90天后到期;創建一個替代品,更新您的應用程序,然後撤銷以前的代幣。 禁用網關將保留代幣,但暫停其使用。 恢復實例狀態會禁用網關並清除代幣權限;創建新代幣。

錯誤使用 error.message, error.type, error.code 和 error.param。 閱讀代碼以及 HTTP 狀態。 不要自動重複一代未知的結果:它可能已經消耗了供應商配額。 示例禁用 SDK 重複。

未知的提供者重置時間仍然未知。 永遠不要從模型名稱或無關的供應商的配額時間表中提取一個。

使用應用程序中的另一個實例

外部應用程式可使用另一個自有執行個體的 Base URL 和由它簽發的權杖存取該執行個體。每個權杖只屬於簽發它的執行個體。若要讓 B 的代理程式處理 A 的專案，請在 B 建立權杖時選擇 另一個執行個體，並參閱遠端工作階段。預設情況下，檔案與命令仍留在 A。在 A 儲存該連線，於 新工作階段 → 執行位置 選擇 B，並保留 專案位置 → 此執行個體。若要使用 B 的專案，請在 B 建立權杖時選擇 此執行個體 與對應專案，並在 A 啟動時選擇 專案位置 → 遠端執行個體。兩種方式都會即時傳送事件。一般權杖支援文字與圖片，但不會讓用戶端以遠端擁有者身分登入。Responses、Anthropic Messages 和 Chat Completions 的工具呼叫不在文字 API 的支援範圍內。

有關 AI輔助整合的信息,請參閱 文檔 AI, 原始 Markdown 指南, OpenAPI 方案,以及 整合技能。

程式碼範例

在運行示例之前,設置上面的三個環境變量。 這些片段也可在設置和原始 Markdown 指南中使用。

set -euo pipefail
# The token is read from standard input, not a command-line argument.
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/models" --header @- <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

body=$(jq -n --arg model "$AIRCODE_AI_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello!"}]}')
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/chat/completions" \
  --header 'Content-Type: application/json' \
  --header @- --data "$body" <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

import os
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    base_url=os.environ["AIRCODE_AI_BASE_URL"],
    api_key=os.environ["AIRCODE_AI_TOKEN"],
    max_retries=0,
    http_client=DefaultHttpx2Client(follow_redirects=False),
)

for model in client.models.list():
    print(model.id)

response = client.chat.completions.create(
    model=os.environ["AIRCODE_AI_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

function required(name) {
  if (!process.env[name]) throw new Error("Set " + name + " first.");
  return process.env[name];
}

const client = new OpenAI({
  baseURL: required("AIRCODE_AI_BASE_URL"),
  apiKey: required("AIRCODE_AI_TOKEN"),
  maxRetries: 0,
  fetchOptions: { redirect: "error" },
});

const stream = await client.chat.completions.create({
  model: required("AIRCODE_AI_MODEL"),
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true },
});

try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
    if (chunk.usage) console.error("Tokens:", chunk.usage.total_tokens);
  }
  process.stdout.write("\n");
} finally {
  stream.controller.abort();
}

SDK 配置參照:OpenAI Python SDK 應用程序和 OpenAI JavaScript SDK 編輯器. 此網關支持上面文檔中的子集。