APIMaster.ai
Tài liệu APIMaster.ai
Quick startAPIMaster.aiMarketplace

Thiết lập API Key OpenCode AI — Cấu hình tương thích OpenAI

Cách cấu hình OpenCode AI với API key tùy chỉnh từ APIMaster.ai. Thêm APIMaster làm nhà cung cấp tương thích OpenAI trong opencode.jsonc và truy cập Claude, GPT-5.5, DeepSeek với đầu vào hình ảnh (Vision) và các tầng Reasoning tùy chọn.

OpenCode Desktop là ứng dụng đồ họa cho OpenCode (hiện đang ở bản beta): các phiên tác nhân cục bộ, chỉnh sửa tệp và thực thi shell. APIMaster.ai tương thích với OpenAI — thêm nó trong Cài đặt → Nhà cung cấp → Nhà cung cấp tùy chỉnh.

Lấy API Key trước. Sử dụng placeholder your_apimaster_key bên dưới; ảnh chụp màn hình che các khóa thật.

Điều kiện tiên quyết

  1. OpenCode Desktop đã được cài đặt từ opencode.ai/download.
    • Windows: opencode-desktop-win-x64.exe
    • macOS: brew install --cask opencode-desktop hoặc .dmg
    • Linux: .deb / .rpm / AppImage
  2. API Key APIMaster từ bảng điều khiển.

Bước 1 — Mở Nhà cung cấp

  1. Khởi chạy OpenCode Desktop và mở một workspace.
  2. Nhấp vào biểu tượng bánh răng (góc dưới bên trái).
  3. Chọn Nhà cung cấp trong thanh bên.
  4. Cuộn đến Nhà cung cấp tùy chỉnh (Thêm nhà cung cấp tương thích OpenAI bằng base URL).
  5. Nhấp vào + Kết nối.

Cài đặt → Nhà cung cấp → Nhà cung cấp tùy chỉnh

Bước 2 — Biểu mẫu nhà cung cấp tùy chỉnh

Trường Giá trị
ID Nhà cung cấp apimaster
Tên hiển thị APIMaster.ai
Base URL https://apimaster.ai/v1
API key Khóa APIMaster của bạn

Biểu mẫu nhà cung cấp tùy chỉnh

Để trống Tiêu đề trừ khi bạn xác thực chỉ qua tiêu đề.

Bước 3 — Thêm mô hình & Gửi

Trên màn hình tiếp theo, ánh xạ các mô hình (bên trái = nhãn trong OpenCode, bên phải = id mô hình gửi đến APIMaster — thường giống nhau):

Bên trái Bên phải
gpt-5.4 gpt-5.4
claude-sonnet-4-6 claude-sonnet-4-6
  1. Nhấp vào + Thêm mô hình để có thêm hàng.
  2. Nhấp vào Gửi.

Thêm mô hình và Gửi

Chọn id từ chợ. Tránh các mô hình chỉ dành cho tạo hình ảnh (ví dụ: gpt-image-2) cho trò chuyện tác nhân.

Cần nhận diện hình ảnh (Vision)? gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8, và claude-haiku-4-5 hỗ trợ đầu vào hình ảnh, nhưng OpenCode cần khai báo thêm khả năng — xem Bật đầu vào hình ảnh cho GPT và Claude.

Bước 4 — Chọn mô hình

  1. Bắt đầu hoặc mở một phiên.
  2. Mở trình đơn thả xuống mô hình bên dưới ô nhập.
  3. Trong APIMaster.ai, chọn một mô hình (ví dụ: claude-sonnet-4-6).

Trình chọn mô hình

Bước 5 — Kiểm tra

Gửi hello hoặc một tác vụ mã hóa nhỏ. Một phản hồi Trợ lý bình thường (chỉnh sửa tệp / shell) có nghĩa là APIMaster đã được kết nối.

Kiểm tra trò chuyện

Nâng cao: opencode.jsonc & Reasoning

Luồng giao diện người dùng ở trên là đủ để bắt đầu nhanh. Để cấu hình các bậc Reasoning / thinking effort (low, high, max, …) cho cùng một id mô hình, hãy chỉnh sửa opencode.jsonc.

Vị trí tệp cấu hình

Hệ điều hành Đường dẫn
macOS / Linux ~/.config/opencode/opencode.jsonc
Windows C:\Users\<tên_người_dùng>\.config\opencode\opencode.jsonc

Tạo tệp nếu chưa có. Khởi động lại OpenCode Desktop hoặc bắt đầu một phiên mới sau khi lưu.

API Key (không đặt trong jsonc)

Không lưu trữ API Key của bạn trong opencode.jsonc.

Sử dụng:

  • /connect trong terminal, hoặc
  • Cài đặt → Nhà cung cấp → Kết nối Nhà cung cấp (giống như Bước 1–2 ở trên).

Giữ bí mật trong kho lưu trữ xác thực của OpenCode; jsonc chỉ định nghĩa nhà cung cấp, mô hình và các biến thể Reasoning.

Nhà cung cấp APIMaster trong jsonc

Id nhà cung cấp: apimaster. Gói npm: @ai-sdk/openai-compatible.

baseURL phải là:

https://apimaster.ai/v1

Không phải https://apimaster.ai/ — OpenCode thêm /chat/completions. Nếu không có /v1, bạn sẽ nhận được https://apimaster.ai/chat/completions → 404 Not Found.

Cũng không phải https://api.apimaster.ai/v1 — host có tiền tố api. có thể gây lỗi TLS / kết nối khi kiểm tra. Host chính xác là https://apimaster.ai/v1.

Ví dụ đầy đủ với các biến thể Reasoning — tải xuống và ghi đè cấu hình của OpenCode:

  1. Tải xuống opencode.jsonc
  2. Ghi đè (hoặc lưu dưới dạng):
    • macOS / Linux: ~/.config/opencode/opencode.jsonc
    • Windows: C:\Users\<tên_người_dùng>\.config\opencode\opencode.jsonc
  3. Cấu hình API Key qua /connect hoặc giao diện người dùng (không bao giờ trong jsonc).
  4. Khởi động lại OpenCode Desktop hoặc bắt đầu một phiên mới.

Sao lưu tệp hiện tại của bạn trước khi ghi đè, hoặc chỉ hợp nhất khối provider.apimaster.

Hình dạng tối thiểu:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://apimaster.ai/v1" },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

Các trường attachment và modalities trên gpt-5.5 ở trên bật đầu vào hình ảnh (Vision) — xem Bật đầu vào hình ảnh cho GPT và Claude. Bỏ chúng nếu bạn chỉ cần trò chuyện văn bản.

Nguyên tắc Reasoning

  • variants = nhiều bậc Reasoning cho một id mô hình trong giao diện người dùng.
  • Đối với các API tương thích OpenAI, OpenCode ánh xạ reasoningEffort → reasoning_effort trong phần thân yêu cầu.
  • Tên biến thể phải khớp với tham số thực tế (high → "reasoningEffort": "high").
  • Mỗi mô hình hỗ trợ các bậc khác nhau — cấu hình theo tài liệu chính thức; không có ánh xạ lại ẩn.

Các bậc Reasoning theo mô hình

Mô hình Biến thể Reasoning Ghi chú
gpt-5.4 low, medium, high, xhigh GPT reasoning
gpt-5.5 low, medium, high, xhigh GPT reasoning
deepseek-v4-flash high, max DeepSeek thinking (khuyến nghị)
deepseek-v4-pro high, max DeepSeek thinking (khuyến nghị)
claude-sonnet-4-6 low, medium, high, max Claude Sonnet effort
claude-opus-4-7 low, medium, high, xhigh, max Claude Opus effort
claude-opus-4-8 low, medium, high, xhigh, max Claude Opus effort
claude-haiku-4-5 không có Không có bậc effort chưa được xác nhận
minimax-m3 không có Không có bậc effort chưa được xác nhận

Xem opencode.jsonc để biết tệp đầy đủ.

Chuyển đổi Reasoning trong OpenCode

  1. Lưu opencode.jsonc, sau đó khởi động lại hoặc phiên mới.
  2. Sử dụng trình đơn thả xuống mô hình / Reasoning (ví dụ: gpt-5.4 / high).
  3. Nếu được hỗ trợ trong bản dựng của bạn: Ctrl + Shift + D sẽ chuyển đổi các bậc Reasoning.

Bật đầu vào hình ảnh cho GPT và Claude

Các mô hình APIMaster.ai như gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8, và claude-haiku-4-5 hỗ trợ đầu vào hình ảnh / Vision — đọc ảnh chụp màn hình, ảnh chụp, biểu đồ để nhận diện, mô tả, OCR, hoặc lập trình từ một hình ảnh.

Mô hình hỗ trợ hình ảnh ≠ OpenCode gửi hình ảnh. Mặc dù bản thân mô hình APIMaster.ai hỗ trợ vision, bạn phải khai báo khả năng trong opencode.jsonc. Nếu không, OpenCode có thể không gửi hình ảnh dưới dạng đầu vào đa phương thức — nó chỉ đặt tên tệp đính kèm vào prompt, và mô hình trả lời đại loại như "mô hình hiện tại không hỗ trợ đầu vào hình ảnh."

Hai trường cần khai báo

Đối với mỗi mô hình bạn muốn dùng với hình ảnh, hãy thêm:

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • attachment: true cho OpenCode biết mô hình này chấp nhận tệp đính kèm.
  • modalities.input chứa "image" cho OpenCode biết mô hình này hỗ trợ đầu vào hình ảnh, nên OpenCode chuyển hình ảnh thành nội dung đa phương thức image_url.

Ví dụ đầy đủ (GPT và Claude)

Tải xuống opencode.jsonc (đã bao gồm các trường), hoặc hợp nhất khối provider.apimaster bên dưới vào cấu hình hiện tại của bạn:

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" }
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-7": {
          "name": "claude-opus-4-7",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-8": {
          "name": "claude-opus-4-8",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-haiku-4-5": {
          "name": "claude-haiku-4-5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Ghi chú:

  • Để chỉ bật đầu vào hình ảnh cho gpt-5.5, thêm attachment và modalities chỉ cho gpt-5.5; giữ nguyên các mô hình khác.
  • Để chỉ bật cho Claude, thêm các trường này chỉ cho các mô hình Claude.
  • Giữ nguyên các biến thể Reasoning hiện có của mỗi mô hình (low / medium / high / xhigh / max) — các trường hình ảnh và Reasoning không xung đột.
  • Sau khi chỉnh sửa opencode.jsonc, hãy thoát hẳn và khởi động lại OpenCode, hoặc ít nhất bắt đầu một phiên mới, để cấu hình được tải lại.
  • Không bao giờ đặt API Key trong tệp này — cấu hình nó qua /connect hoặc giao diện người dùng (xem Bảo mật bên dưới).

Nguồn hình ảnh: ưu tiên tải lên cục bộ / base64

  • Khuyến nghị: tải lên một tệp PNG / JPG cục bộ trong OpenCode. Lý tưởng nhất là OpenCode chuyển nó thành base64 data URL (data:image/png;base64,...) trước khi gửi đến APIMaster — đây là đường dẫn đã được xác minh hoạt động.
  • Truyền trực tiếp một URL hình ảnh công khai có thể thất bại. APIMaster / nguồn ngược dòng có thể không tải được hình ảnh công khai do mạng, định dạng, kích thước, MIME, hoặc bảo vệ chống hotlink, trả về:
    Error while downloading file. Upstream status code: 400.
    Trong trường hợp đó, hãy dùng base64 data URL hoặc tải lên cục bộ thay vì dựa vào phía mô hình để tải một URL công khai.

Kiểm tra rằng nhận diện hình ảnh hoạt động

Phương án A — Kiểm tra trong OpenCode

  1. Chuyển sang apimaster/gpt-5.5 hoặc apimaster/claude-sonnet-4-6 trong trình đơn thả xuống mô hình.
  2. Tải lên một hình ảnh PNG / JPG.
  3. Nhập:
    Describe the main content of this image.
  • Với cấu hình đúng, mô hình sẽ mô tả nội dung hình ảnh.
  • Nếu mô hình chỉ đề cập đến một tên tệp / tệp đính kèm, hoặc trả lời "image input not supported," thì có khả năng OpenCode không gửi nội dung hình ảnh — kiểm tra các trường attachment và modalities của mô hình và khởi động lại OpenCode.

Phương án B — Kiểm tra trực tiếp qua API

Hữu ích để phân biệt vấn đề của mô hình APIMaster với vấn đề của adapter OpenCode. Không bao giờ mã hóa cứng một khóa thật — dùng một biến môi trường.

Linux / macOS:

export APIMASTER_API_KEY="your APIMaster API key"

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image." },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,YOUR_IMAGE_BASE64"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

Đổi model thành claude-sonnet-4-6 để kiểm tra Claude theo cách tương tự (đã xác minh HTTP 200 với nhận diện hình ảnh).

Windows PowerShell:

$env:APIMASTER_API_KEY = "your APIMaster API key"
# Convert a local image to base64, put it into image_url.url as data:image/png;base64,...
# Then call https://apimaster.ai/v1/chat/completions with the same JSON body.

Một phản hồi 200 mô tả được hình ảnh có nghĩa là đầu vào hình ảnh hoạt động ở phía APIMaster; nếu OpenCode vẫn thất bại, vấn đề nằm ở cấu hình attachment / modalities của OpenCode hoặc thiếu khởi động lại.

Khắc phục sự cố

Thiết lập giao diện người dùng

Vấn đề Khắc phục
401 Kiểm tra khóa; xoay vòng nếu bị lộ
Không tìm thấy mô hình Base URL phải là https://apimaster.ai/v1; id mô hình phải khớp với chợ
Không có mô hình APIMaster Chỉnh sửa nhà cung cấp trong Cài đặt → thêm ánh xạ → Gửi
Chậm / hết thời gian chờ Thử một mô hình khác; sử dụng API Key Tester

Reasoning / jsonc

Tại sao chỉ có high và max cho DeepSeek?
Thinking effort tương thích OpenAI chính thức cho DeepSeek là high và max. Tránh low / medium / xhigh vì chúng có thể được ánh xạ lại một cách khó đoán.

Tại sao max cho Claude Sonnet, không phải xhigh?
Bậc cao nhất của Sonnet là max; xhigh dành cho Opus (claude-opus-4-7 / claude-opus-4-8).

Tại sao không có biến thể cho Haiku hoặc MiniMax M3?
Nếu không có giá trị reasoningEffort được ghi lại, hãy bỏ qua các biến thể — mô hình vẫn hoạt động; giao diện người dùng sẽ không hiển thị các bậc phụ Reasoning.

Vẫn gặp lỗi 400?

  1. baseURL = https://apimaster.ai/v1 (không phải gốc trang web).
  2. Cách viết id mô hình khớp với chợ.
  3. Khóa được cấu hình qua /connect hoặc giao diện người dùng.
  4. Tạm thời xóa variants — nếu các yêu cầu đơn giản hoạt động, thì reasoning_effort đã chọn có thể không được hỗ trợ cho mô hình đó.

Đầu vào hình ảnh / Vision

Tại sao OpenCode nói "the current model does not support image input"?

  • gpt-5.5 và một số mô hình Claude của APIMaster.ai có hỗ trợ đầu vào hình ảnh; thông báo này thường có nghĩa là OpenCode không gửi hình ảnh dưới dạng đầu vào đa phương thức.
  • Kiểm tra rằng mô hình trong opencode.jsonc có:
    "attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • Xác nhận bạn đã khởi động lại OpenCode sau khi chỉnh sửa.
  • Xác nhận baseURL là https://apimaster.ai/v1.
  • Xác nhận API Key APIMaster hợp lệ.
  • Nếu một URL hình ảnh công khai thất bại, hãy dùng base64 data URL hoặc tải lên cục bộ.

Tại sao mô hình chỉ thấy tên tệp đính kèm, không thấy hình ảnh?

  • Thường thì OpenCode không đọc và chuyển tệp đính kèm thành đầu vào hình ảnh — nó chỉ đặt tên tệp / tệp đính kèm vào prompt.
  • Bật attachment: true và modalities.input: ["text", "image"], và dùng một mô hình hỗ trợ đầu vào hình ảnh.

Tại sao một URL hình ảnh công khai báo lỗi?

  • APIMaster hoặc nguồn ngược dòng có thể bị giới hạn bởi mạng, định dạng, kích thước tệp, MIME, bảo vệ chống hotlink, hoặc proxy khi tải một hình ảnh công khai.
  • Với lỗi Error while downloading file. Upstream status code: 400., hãy chuyển sang base64 data URL.

Vẫn không hoạt động sau khi thêm attachment?

  1. Thoát hẳn và khởi động lại OpenCode.
  2. Bắt đầu một phiên mới để kiểm tra.
  3. Xác nhận mô hình đang hoạt động của phiên đúng là mô hình bạn đã cấu hình với các trường hình ảnh.
  4. Xác nhận API Key hợp lệ.
  5. Kiểm tra nhật ký OpenCode để tìm các lỗi 401 / 400 / unsupported image / invalid content type.
  6. Dùng Phương án B — Kiểm tra trực tiếp qua API với một hình ảnh base64 để phân biệt vấn đề của mô hình APIMaster với vấn đề của adapter OpenCode.

Bảo mật

  • Không đặt API Key APIMaster trong opencode.jsonc; tệp đó chỉ chứa nhà cung cấp, mô hình, khả năng hình ảnh, và Reasoning.
  • Không dán khóa vào trò chuyện, ảnh chụp màn hình, issue, tài liệu công khai, hoặc kho mã.
  • Xoay vòng các khóa đã xuất hiện trong ảnh chụp màn hình hoặc nhật ký — thu hồi và tạo lại trong bảng điều khiển, sau đó cập nhật nhà cung cấp trong OpenCode.
  • Ưu tiên luồng /connect của OpenCode, biến môi trường, hoặc kho lưu trữ thông tin xác thực cục bộ để quản lý API Key.
  • OpenCode có thể đọc/ghi tệp và chạy lệnh shell — chỉ sử dụng các workspace đáng tin cậy.

Danh sách kiểm tra

  • OpenCode Desktop đã được cài đặt
  • Nhà cung cấp tùy chỉnh đã được kết nối hoặc apimaster trong opencode.jsonc
  • Base URL / baseURL = https://apimaster.ai/v1 (không phải https://apimaster.ai/)
  • API Key qua /connect hoặc giao diện người dùng (không phải trong jsonc)
  • Ít nhất một mô hình trò chuyện đã được ánh xạ
  • (Tùy chọn) Các biến thể Reasoning khớp với các bậc chính thức
  • Tin nhắn kiểm tra thành công

Danh sách kiểm tra đầu vào hình ảnh

  • baseURL là https://apimaster.ai/v1 (không phải https://api.apimaster.ai/v1)
  • Dùng một mô hình có khả năng vision, ví dụ gpt-5.5 hoặc một mô hình Claude có khả năng Vision
  • Mô hình có attachment: true
  • modalities.input của mô hình chứa "image"
  • OpenCode đã khởi động lại sau khi chỉnh sửa opencode.jsonc
  • API Key hợp lệ
  • Hình ảnh kiểm tra là định dạng phổ biến (PNG / JPG)
  • Nếu một URL hình ảnh công khai thất bại, đã thử một base64 data URL

Tóm tắt

  • Các khóa: baseURL (https://apimaster.ai/v1), id mô hình, API Key (/connect hoặc giao diện người dùng), tùy chọn Biến thể Reasoning.
  • Tên biến thể = giá trị reasoning_effort thực tế.
  • Cấu hình các bậc theo từng mô hình; bỏ qua các biến thể khi không được hỗ trợ (Haiku, MiniMax M3).

Xem thêm