Định dạng API

OpenAI Format

Cách tra cứu và gọi modelTìm model theo nhóm giá, đọc bảng giá Input/Output rồi cấu hình Claude Code hoặc OpenAI SDK để gọi model.

Cài đặt

code
npm install openai

hoặc

code
yarn add openai

Khởi tạo Client

code
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'your-shopaikey-api-key',
  baseURL: 'https://api.shopaikey.com/v1',
});

Chat Completions

Gọi API cơ bản

code
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Xin chào!' }
  ],
  max_tokens: 1000,
  temperature: 1.0,
});

console.log(completion.choices[0].message.content);

Streaming Response

code
const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Kể cho tôi một câu chuyện dài' }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  if (content) {
    process.stdout.write(content);
  }
}

Vision API (Nhận diện hình ảnh)

code
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Bức ảnh này có nội dung gì? Hãy mô tả chi tiết.'
        },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/image.png'
          }
        }
      ]
    }
  ],
  max_tokens: 1000,
});

console.log(completion.choices[0].message.content);

Vision với Base64 Image

code
const fs = require('fs');

const imageBuffer = fs.readFileSync('./image.jpg');
const base64Image = imageBuffer.toString('base64');
const dataUrl = `data:image/jpeg;base64,${base64Image}`;

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Mô tả hình ảnh này'
        },
        {
          type: 'image_url',
          image_url: {
            url: dataUrl
          }
        }
      ]
    }
  ],
});

Function Calling

code
const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Thời tiết ở Hà Nội hôm nay như thế nào?' }
  ],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Lấy thông tin thời tiết tại một địa điểm',
        parameters: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: 'Tên thành phố hoặc địa điểm',
            },
            unit: {
              type: 'string',
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['location'],
        },
      },
    },
  ],
  tool_choice: 'auto',
});

const message = completion.choices[0].message;
if (message.tool_calls) {
  console.log('Function calls:', message.tool_calls);
}

Xử lý lỗi

code
try {
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error('API Error:', error.status);
    console.error('Message:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

code
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.SHOPAIKEY_API_KEY!,
  baseURL: 'https://api.shopaikey.com/v1',
});

async function chat(message: string): Promise<string> {
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: message }],
  });

  return completion.choices[0].message.content || '';
}

Chi tiết API: Tạo trò chuyện (Stream)

(Create Chat Completion - Stream)

Endpoint này được sử dụng để tạo phản hồi từ mô hình cho một cuộc hội thoại đã cho. Dữ liệu có thể được trả về từng phần (streaming) để hiển thị thời gian thực.

  • Phương thức (Method): POST
  • URL: https://api.shopaikey.com/v1/chat/completions

Mô tả

Đưa ra một lời nhắc (prompt), mô hình sẽ trả về một hoặc nhiều dự đoán hoàn thành. API này cũng có thể trả về xác suất của các token thay thế tại mỗi vị trí.

Thông số Yêu cầu (Request Parameters)

Header Parameters

Tên tham sốGiá trịMô tả
AuthorizationBearer <Token>Bắt buộc. Token xác thực API của bạn.
Content-Typeapplication/jsonBắt buộc. Định dạng dữ liệu gửi đi.
Acceptapplication/json

Body Parameters (application/json)

Tên tham sốKiểuMô tả
modelstringID của mô hình cần sử dụng (ví dụ: gpt-5-mini, gpt-4o).
messagesarrayDanh sách các tin nhắn trong cuộc hội thoại.
max_tokensintegerSố lượng token tối đa để tạo trong phần hoàn thành.
temperaturenumberNhiệt độ lấy mẫu (0 đến 2). Giá trị cao hơn (ví dụ 0.8) làm đầu ra ngẫu nhiên hơn, giá trị thấp hơn (ví dụ 0.2) làm đầu ra tập trung và xác định hơn.
streambooleanNếu true, dữ liệu sẽ được gửi về dưới dạng các sự kiện gửi từ máy chủ (server-sent events).
stream_optionsobjectCác tùy chọn bổ sung cho luồng, ví dụ { "include_usage": true } để nhận thông tin sử dụng token.

Ví dụ Yêu cầu (Request Example)

JSON Body:

code
{
  "model": "gpt-5-mini",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Xin chào"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

Ví dụ gọi API (cURL)

code
curl --location --request POST 'https://api.shopaikey.com/v1/chat/completions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "gpt-5-mini",
    "max_tokens": 1000,
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
    ]
}

Phản hồi (Response)

Trạng thái: 200 OK

code
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\n\nHello there, how may I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

Chi tiết API: Tạo trò chuyện nhận diện hình ảnh (Stream)

(Create Chat Vision - Stream)

Endpoint này cho phép bạn gửi hình ảnh kèm theo câu hỏi văn bản đến các mô hình đa phương thức (như GPT-4o, Claude 3.5 Sonnet) để nhận diện và mô tả nội dung hình ảnh theo thời gian thực.

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/chat/completions

Mô tả

Gửi một lời nhắc bao gồm cả văn bản và URL hình ảnh. Mô hình sẽ trả về mô tả hoặc câu trả lời dựa trên nội dung hình ảnh đó.

Yêu cầu (Request)

Headers

TênGiá trịBắt buộcMô tả
AuthorizationBearer <Token>CóToken xác thực API của bạn.
Content-Typeapplication/jsonCóĐịnh dạng dữ liệu gửi đi.
Acceptapplication/jsonKhông

Body (application/json)

Cấu trúc quan trọng nhất là mảng messages. Thay vì chỉ gửi chuỗi văn bản (content: "string"), bạn cần gửi một mảng các đối tượng nội dung (content: array) bao gồm text và image_url.

code
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Bức ảnh này có nội dung gì? Hãy mô tả chi tiết."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.png"
          }
        }
      ]
    }
  ],
  "stream": true,
  "max_tokens": 1000
}

Giải thích tham số:

  • model: Các mô hình hỗ trợ Vision (ví dụ: gpt-4o, gpt-4-turbo, claude-3-5-sonnet-20240620, gemini-1.5-pro).
  • content (trong messages):
    • type: "text": Phần câu hỏi hoặc lời nhắc văn bản.
    • type: "image_url": Đối tượng chứa đường dẫn hình ảnh.
      • url: Đường dẫn trực tiếp đến ảnh (phải công khai truy cập được) hoặc chuỗi Base64 (định dạng data:image/jpeg;base64,...).

Ví dụ gọi API (cURL)

code
curl --location --request POST 'https://api.shopaikey.com/v1/chat/completions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Trong ảnh này có những gì?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}'

Phản hồi (Response)

Trạng thái: 200 OK

Phản hồi trả về tương tự như API Chat thông thường. Nếu stream: true, dữ liệu sẽ về từng chunk. Dưới đây là ví dụ JSON của một phản hồi hoàn chỉnh (hoặc chunk cuối):

code
{
  "id": "chatcmpl-890",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Trong ảnh là một phong cảnh thiên nhiên tuyệt đẹp với bầu trời xanh..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 50,
    "total_tokens": 170
  }
}

Responses API

OpenAI Responses API dùng để tạo phản hồi mô hình. Hỗ trợ hội thoại nhiều lượt, gọi công cụ, suy luận.

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/responses

Request Body

Tên tham sốKiểuMô tả
modelstringBắt buộc. ID model
inputstring/arrayNội dung đầu vào
instructionsstringHướng dẫn cho model
max_output_tokensintegerSố token đầu ra tối đa
temperaturenumberNhiệt độ lấy mẫu
top_pnumberTham số nucleus sampling
streambooleanPhản hồi dạng stream
toolsarrayDanh sách công cụ
tool_choicestring/objectLựa chọn công cụ
reasoningobjectCấu hình suy luận (effort: low/medium/high)
previous_response_idstringID phản hồi trước (multi-turn)
truncationstringChế độ cắt ngắn (auto/disabled)

Ví dụ

code
const response = await openai.responses.create({
  model: 'gpt-4o',
  input: 'Xin chào!',
  instructions: 'Bạn là trợ lý hữu ích.',
});

console.log(response.output[0].content[0].text);

Response

code
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1700000000,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Xin chào! Tôi có thể giúp gì cho bạn?"
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

Responses Compaction

Nén hội thoại dài (compaction) cho Responses API.

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/responses/compact
Tên tham sốKiểuMô tả
modelstringBắt buộc. ID model
inputstring/arrayNội dung cần nén
instructionsstringHướng dẫn nén
previous_response_idstringID phản hồi trước

Images API

Tạo ảnh

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/images/generations
code
const image = await openai.images.generate({
  model: 'gpt-image-1',
  prompt: 'Một chú mèo nhỏ đội mũ nồi đứng giữa phố cổ',
  n: 1,
  size: '1024x1024',
  quality: 'high',
  response_format: 'url',
});

console.log(image.data[0].url);
Tên tham sốKiểuMô tả
modelstringModel sinh ảnh (dall-e-2, dall-e-3, gpt-image-1)
promptstringBắt buộc. Mô tả ảnh cần tạo
nintegerSố lượng ảnh (1-10)
sizestringKích thước ảnh đầu ra
qualitystringChất lượng ảnh
backgroundstringNền ảnh (transparent/opaque/auto)
stylestringPhong cách ảnh
response_formatstringĐịnh dạng trả về (url/b64_json)

Chỉnh sửa ảnh

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/images/edits
  • Content-Type: multipart/form-data
Tên tham sốKiểuMô tả
imagefileBắt buộc. Ảnh gốc cần chỉnh sửa
promptstringBắt buộc. Mô tả chỉnh sửa
maskfileẢnh mask PNG để chỉ vùng chỉnh sửa
modelstringModel chỉnh sửa ảnh
nstringSố ảnh đầu ra
sizestringKích thước (256x256, 512x512, 1024x1024)

Videos API

Tạo video (OpenAI format)

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/videos
  • Content-Type: multipart/form-data
Tên tham sốKiểuMô tả
modelstringTên model (vd: sora-2)
promptstringPrompt mô tả video
secondsstringSố giây sinh
input_referencefileTệp ảnh tham chiếu

Lấy trạng thái video

  • Phương thức: GET
  • URL: https://api.shopaikey.com/v1/videos/{task_id}

Lấy nội dung video

  • Phương thức: GET
  • URL: https://api.shopaikey.com/v1/videos/{task_id}/content

Trả về luồng tệp video (video/mp4).

Tạo video (Generic format)

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/video/generations
Tên tham sốKiểuMô tả
modelstringID model (vd: kling-v1)
promptstringPrompt mô tả
imagestringẢnh đầu vào (URL hoặc Base64)
durationnumberThời lượng video (giây)
widthintegerChiều rộng video
heightintegerChiều cao video
fpsintegerTốc độ khung hình
seedintegerHạt giống ngẫu nhiên
nintegerSố lượng video

Lấy trạng thái video (Generic format)

  • Phương thức: GET
  • URL: https://api.shopaikey.com/v1/video/generations/{task_id}

Embeddings API

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/embeddings
code
const embedding = await openai.embeddings.create({
  model: 'text-embedding-ada-002',
  input: 'Xin chào thế giới',
});

console.log(embedding.data[0].embedding);
Tên tham sốKiểuMô tả
modelstringBắt buộc. ID model (vd: text-embedding-ada-002)
inputstring/arrayBắt buộc. Văn bản cần nhúng
encoding_formatstringĐịnh dạng (float/base64)
dimensionsintegerSố chiều vector đầu ra

Audio API

Text-to-Speech

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/audio/speech
code
const mp3 = await openai.audio.speech.create({
  model: 'tts-1',
  voice: 'alloy',
  input: 'Xin chào, tôi là trợ lý AI.',
});
Tên tham sốKiểuMô tả
modelstringBắt buộc. Model TTS (vd: tts-1)
inputstringBắt buộc. Văn bản cần chuyển đổi (tối đa 4096 ký tự)
voicestringBắt buộc. Giọng nói (alloy/echo/fable/onyx/nova/shimmer)
response_formatstringĐịnh dạng (mp3/opus/aac/flac/wav/pcm)
speednumberTốc độ (0.25 - 4.0)

Phiên âm (Transcription)

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/audio/transcriptions
  • Content-Type: multipart/form-data
Tên tham sốKiểuMô tả
filefileBắt buộc. Tệp âm thanh
modelstringBắt buộc. Model (vd: whisper-1)
languagestringMã ngôn ngữ ISO-639-1
response_formatstringĐịnh dạng (json/text/srt/verbose_json/vtt)

Dịch âm thanh (Translation)

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/audio/translations
  • Content-Type: multipart/form-data
Tên tham sốKiểuMô tả
filefileBắt buộc. Tệp âm thanh
modelstringBắt buộc. Model (vd: whisper-1)

Completions API (Legacy)

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/completions
Tên tham sốKiểuMô tả
modelstringBắt buộc. ID model
promptstring/arrayBắt buộc. Prompt đầu vào
max_tokensintegerSố token tối đa
temperaturenumberNhiệt độ lấy mẫu
streambooleanPhản hồi dạng stream

Rerank API

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/rerank
code
const result = await fetch('https://api.shopaikey.com/v1/rerank', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'rerank-english-v2.0',
    query: 'What is machine learning?',
    documents: ['ML is a subset of AI', 'Cooking recipes', 'Deep learning models'],
    top_n: 2,
  }),
});
Tên tham sốKiểuMô tả
modelstringBắt buộc. Model rerank
querystringBắt buộc. Văn bản truy vấn
documentsarrayBắt buộc. Danh sách tài liệu
top_nintegerTrả về N kết quả đầu tiên
return_documentsbooleanTrả về nội dung tài liệu

Moderations API

  • Phương thức: POST
  • URL: https://api.shopaikey.com/v1/moderations
Tên tham sốKiểuMô tả
inputstring/arrayBắt buộc. Nội dung cần kiểm duyệt
modelstringModel kiểm duyệt (vd: text-moderation-latest)

Realtime API (WebSocket)

  • Phương thức: GET (WebSocket upgrade)
  • URL: wss://api.shopaikey.com/v1/realtime?model=gpt-4o-realtime-preview

Thiết lập kết nối WebSocket cho hội thoại thời gian thực.

Tên tham sốKiểuMô tả
modelquery stringModel sử dụng (vd: gpt-4o-realtime-preview)

Liệt kê Models

  • Phương thức: GET
  • URL: https://api.shopaikey.com/v1/models
code
const models = await openai.models.list();
console.log(models.data);

Bài cùng nhóm · Định dạng API