Hướng dẫn tích hợp

Tổng quan

Xác thực

Lưu key trong biến môi trường và gửi qua header Authorization.

export TMT_AI_KEY="sk-..."

curl https://ai.devmin.net/v1/models \
  -H "Authorization: Bearer $TMT_AI_KEY"

Thiếu hoặc sai key trả về 401.

Liệt kê mô hình

Trả về các mô hình mà key của bạn được phép dùng. Giá trị id chính là tên điền vào trường model.

{
  "object": "list",
  "data": [
    {"id": "gemma-3-4b", "object": "model", ...},
    {"id": "qwen3-embedding", "object": "model", ...}
  ]
}

Gợi ý chọn mô hình

Chat completions

curl https://ai.devmin.net/v1/chat/completions \
  -H "Authorization: Bearer $TMT_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-3-4b",
    "messages": [
      {"role": "system", "content": "Bạn là trợ lý ngắn gọn."},
      {"role": "user",   "content": "Giải thích REST trong 2 câu."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

Kết quả nằm ở choices[0].message.content; mức dùng ở usage (prompt_tokens, completion_tokens).

Streaming

Thêm "stream": true để nhận kết quả dần theo chuẩn Server-Sent Events; luồng kết thúc bằng data: [DONE].

from openai import OpenAI
client = OpenAI(base_url="https://ai.devmin.net/v1", api_key="<TMT_AI_KEY>")

stream = client.chat.completions.create(
    model="gemma-3-4b", stream=True,
    messages=[{"role": "user", "content": "Đếm từ 1 đến 5"}],
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Vision

Dùng mô hình vision và đưa ảnh vào content dạng mảng. Ảnh có thể là URL công khai hoặc data: base64.

{
  "model": "qwen3-vl-8b",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Ảnh này có gì?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/anh.jpg"}}
    ]
  }]
}

Ảnh nên thu nhỏ trước khi gửi (cạnh dài khoảng 1024–1536 px) để giảm độ trễ và dung lượng yêu cầu.

Tool calling & JSON

Các mô hình hỗ trợ sẽ nhận tools/tool_choice và response_format theo chuẩn OpenAI.

{
  "model": "gpt-4.1",
  "messages": [{"role": "user", "content": "Thời tiết Hà Nội?"}],
  "tools": [{"type": "function", "function": {
    "name": "get_weather",
    "parameters": {"type": "object",
      "properties": {"city": {"type": "string"}}, "required": ["city"]}
  }}],
  "tool_choice": "auto"
}

Để buộc đầu ra là JSON hợp lệ, thêm "response_format": {"type": "json_object"} và nói rõ định dạng mong muốn trong prompt. Mức hỗ trợ khác nhau theo mô hình; mô hình nhỏ có thể cần thử nghiệm thêm.

Embeddings

curl https://ai.devmin.net/v1/embeddings \
  -H "Authorization: Bearer $TMT_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-embedding", "input": ["xin chào", "hello world"]}'

input là chuỗi hoặc mảng chuỗi. Mỗi phần tử ở data[i].embedding là một vector số thực. Dùng cùng một mô hình cho cả tài liệu và truy vấn; đổi mô hình thì phải vector hoá lại toàn bộ dữ liệu.

Nhận dạng giọng nói

curl https://ai.devmin.net/v1/audio/transcriptions \
  -H "Authorization: Bearer $TMT_AI_KEY" \
  -F model=whisper-large-v3 \
  -F language=vi \
  -F file=@ghi-am.mp3

Trả về JSON có trường text. Chỉ định language (ví dụ vi) giúp tăng độ chính xác và giảm thời gian xử lý.

Tổng hợp giọng nói

curl https://ai.devmin.net/v1/audio/speech \
  -H "Authorization: Bearer $TMT_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "voxcpm2", "input": "Xin chào, đây là giọng đọc thử.", "voice": "nu-luu-loat"}' \
  -o speech.wav

Phản hồi là dữ liệu âm thanh (WAV) ghi thẳng vào file. Trường voice phụ thuộc mô hình; hỏi TMT Cloud danh sách giọng được bật cho key của bạn.

SDK & công cụ

Python (openai)

pip install openai

from openai import OpenAI
client = OpenAI(base_url="https://ai.devmin.net/v1", api_key="<TMT_AI_KEY>")
print(client.chat.completions.create(model="gpt-4.1",
      messages=[{"role": "user", "content": "Xin chào"}]).choices[0].message.content)

Node.js

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://ai.devmin.net/v1", apiKey: process.env.TMT_AI_KEY });

Biến môi trường (nhiều công cụ đọc sẵn)

export OPENAI_BASE_URL="https://ai.devmin.net/v1"
export OPENAI_API_KEY="<TMT_AI_KEY>"

Công cụ có giao diện (Open WebUI, Continue, Cline, Cherry Studio…)

Chọn nhà cung cấp OpenAI Compatible, điền API Base URL = https://ai.devmin.net/v1, API Key = key của bạn, rồi nhập tên mô hình (ví dụ qwen2.5-coder cho trợ lý code).

Mã lỗi

Thân lỗi có dạng {"error": {"message": "...", "type": "...", "code": "..."}}.

Giới hạn & khuyến nghị

• Tốc độ: cổng giới hạn mặc định khoảng 40 yêu cầu/giây mỗi địa chỉ IP (cho phép đột biến ngắn đến 80). Hạn mức theo key do TMT Cloud đặt riêng.
• Timeout: đặt timeout phía client từ 60–120 giây cho chat, lâu hơn cho ảnh/âm thanh dài.
• Thử lại: chỉ thử lại với 429/5xx, kèm backoff và jitter; đừng thử lại vô hạn.
• Chi phí: mỗi nhóm mô hình có cách tính khác nhau; theo dõi usage trong phản hồi.
• Dữ liệu nhạy cảm: hãy trao đổi với TMT Cloud về mô hình phù hợp trước khi gửi dữ liệu nhạy cảm.
• Tính ổn định: danh mục mô hình có thể thay đổi; luôn kiểm tra bằng GET /v1/models thay vì mã hoá cứng danh sách.

Hỗ trợ

Cần cấp key, thêm mô hình, tăng hạn mức hoặc báo sự cố: liên hệ đội kỹ thuật TMT Cloud qua kênh bạn đang làm việc với chúng tôi, hoặc tmtcloud.vn. Khi báo lỗi, vui lòng gửi thời điểm, tên mô hình và mã HTTP (không gửi kèm API key).

Tham chiếu đầy đủ các điểm cuối: ReDoc · openapi.json.