> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tai-lieu-api/introduction/openai-compatibility.md). # Tương thích OpenAI Trỏ SDK `openai` chính thức hoặc bất kỳ công cụ nào dùng OpenAI API đến Avis. Đặt Avis API key của bạn trong `apiKey` (xem phần Xác thực). ### Base URL ``` https://api.avis.net/api/openai/v1 ``` ### Chuyển đổi một ứng dụng hiện có ```typescript import OpenAI from 'openai' const client = new OpenAI({ apiKey: process.env.AVIS_API_KEY, baseURL: 'https://api.avis.net/api/openai/v1', }) ``` Bạn không cần thay đổi phần nào khác trong tích hợp OpenAI hiện có. ### Endpoints | Method | Path | Streaming | Mô tả | | ------ | ----------------------------------- | -------------------- | ----------------------------------------------- | | `HEAD` | `/api/openai` | — | Kiểm tra kết nối (không cần xác thực) | | `GET` | `/api/openai/v1/models` | — | Liệt kê các mô hình khả dụng | | `POST` | `/api/openai/v1/chat/completions` | ✅ | Chat completions | | `POST` | `/api/openai/v1/images/generations` | ✅ (tùy nhà cung cấp) | Tạo hình ảnh | | `POST` | `/api/openai/v1/videos` | — | Gửi một job tạo video bất đồng bộ | | `GET` | `/api/openai/v1/videos/:id` | — | Poll trạng thái job video | | `GET` | `/api/openai/v1/videos/:id/content` | — | Tải xuống video đã tạo | | `POST` | `/api/openai/v1/responses` | ✅ | Responses API (được Codex CLI/Desktop sử dụng) | | `POST` | `/api/openai/v1/embeddings` | — | Embedding văn bản; chỉ hỗ trợ vector dạng float | #### `POST /chat/completions` ```typescript const response = await client.chat.completions.create({ model: 'gpt-4-1-mini', messages: [{ role: 'user', content: 'Hello!' }], }) console.log(response.choices[0].message.content) ``` #### `POST /images/generations` ```typescript import { writeFileSync } from 'node:fs' const response = await client.images.generate({ model: 'seedream-4-0', prompt: 'A simple red apple on a white table, photorealistic', n: 1, size: '1024x1024', response_format: 'b64_json', }) writeFileSync('output.jpg', Buffer.from(response.data[0].b64_json!, 'base64')) console.log('Image saved to output.jpg') ``` #### `POST /videos` — job bất đồng bộ ```typescript import { writeFileSync } from 'node:fs' const job = await client.videos.create({ model: 'veo-3-1', prompt: 'A red apple falling from a tree in slow motion, photorealistic', }) console.log('Job submitted:', job.id, '| status:', job.status) let video = job while (video.status !== 'completed' && video.status !== 'failed') { await new Promise((r) => setTimeout(r, 3000)) video = await client.videos.retrieve(job.id) console.log('Status:', video.status) } if (video.status !== 'completed') { throw new Error(`Video generation failed. Status: ${video.status}`) } const content = await client.videos.downloadContent(video.id) writeFileSync('output.mp4', Buffer.from(await content.arrayBuffer())) console.log('Video saved to output.mp4 (via downloadContent)') ``` Hiện tại, các mô hình video được hỗ trợ chỉ được định tuyến qua OpenRouter. #### `POST /embeddings` ```typescript const response = await client.embeddings.create({ model: 'text-embedding-3-small', input: 'The quick brown fox jumps over the lazy dog.', }) console.log(response.data[0].embedding) ``` `input` cũng nhận mảng chuỗi để tạo embedding theo lô, tối đa 128 chuỗi trong một lệnh gọi. Định dạng truyền tải OpenAI không hỗ trợ đầu vào đa phương thức (hình ảnh/âm thanh/tệp, cũng như video với `gemini-embedding-2`/`gemini-embedding-2-preview`). Hãy gửi trực tiếp body request cấp thấp, hoặc dùng giao diện tương thích Gemini hay Anthropic; cả hai đều nhận đầu vào dạng content-block đã được Avis chuẩn hóa. #### `GET /models` ```typescript const models = await client.models.list() console.log(models.data[0]) ``` ### Hỗ trợ các trường Proxy này hoạt động như một **lớp chuyển tiếp mỏng**. Các trường request chủ yếu tuân theo định nghĩa upstream tương thích OpenAI và được chuyển tiếp nguyên vẹn. Việc một trường có được áp dụng hay không phụ thuộc vào nhà cung cấp và mô hình được chọn. ### Response của `/models` | Trường | Kiểu | Bắt buộc | Ghi chú | | --------------------------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | ✅ | Model ID dành cho người dùng, dùng trong `model` cho các lệnh gọi tương thích OpenAI | | `name` | `string` | — | Tên mô hình dễ đọc | | `inputModalities` | `array` | — | Các loại dữ liệu đầu vào được mô hình hỗ trợ | | `outputModalities` | `array` | — | Các loại dữ liệu đầu ra được mô hình hỗ trợ | | `capabilitiesProviderId` | `string` | — | Bản ghi nhà cung cấp được chọn theo độ ưu tiên để xác định khả năng | | `capabilities` | `object` | — | Đối tượng khả năng thực tế của bản ghi nhà cung cấp có độ ưu tiên cao nhất. Nếu không có nghĩa là không bị ràng buộc. | | `capabilities.text.supportedParameters` | `array` | — | Với mô hình văn bản: các tham số tạo nội dung được chấp nhận (ví dụ `maxTokens`, `temperature`, `topP`, `tools`, `thinking`). | | `capabilities.params` | `object` | — | Giới hạn/ràng buộc của từng tham số, theo tên trường trong request. Với mô hình hình ảnh/video, đọc từ `capabilities.image.params` hoặc `capabilities.video.params`. | | `capabilities.inputs` | `object` | — | Các đầu vào dạng content-part được chấp nhận (vai trò, loại media, giới hạn). | | `capabilities.strictParams` | `boolean` | — | Khi là `true`, các tham số có kiểm soát mà không được hỗ trợ sẽ bị từ chối. | | `chatPricing` | `object` | — | Metadata giá chat thực tế của bản ghi nhà cung cấp được chọn | | `imagePricing` | `object` | — | Metadata giá hình ảnh thực tế của bản ghi nhà cung cấp được chọn | | `videoPricing` | `object` | — | Metadata giá video thực tế của bản ghi nhà cung cấp được chọn | | `threeDPricing` | `object` | — | Metadata giá 3D thực tế của bản ghi nhà cung cấp được chọn | | `embeddingPricing` | `object` | — | Metadata giá embedding thực tế của bản ghi nhà cung cấp được chọn | #### Cấu trúc giá trị của `capabilities.params` Với các mô hình hình ảnh/video, hãy dùng `capabilities.image.params` hoặc `capabilities.video.params` của từng mô hình thay vì cố định các giới hạn dùng chung cho mọi mô hình. | `type` | Trường bổ sung | Ý nghĩa | | ------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `enum` | `values: string[]`, `default?` | Giá trị phải là một trong các `values`. | | `range` | `min`, `max`, `default?`, `unit?`, `steps?: number[]` | Giá trị phải nằm giữa `min` và `max`. Khi có `steps`, chỉ các giá trị chính xác đó mới hợp lệ. | | `int` | `min`, `max`, `default?` | Giá trị phải là một số nguyên nằm giữa `min` và `max`. | | `bool` | `default?` | Giá trị phải là `true` hoặc `false`. | ### `/chat/completions` | Trường | Kiểu | Bắt buộc | Ghi chú | | ------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------- | | `model` | `string` | ✅ | OpenAI model ID; được phân giải và đổi thành model ID của nhà cung cấp trước khi chuyển tiếp | | `messages` | `array` | ✅ | Mảng tin nhắn chat chuẩn | | `temperature` | `number` | — | Điều khiển lấy mẫu | | `max_tokens` | `number` | — | Số token completion tối đa | | `stream` | `boolean` | — | Bật response dạng SSE; dùng để chọn luồng xử lý streaming | | `stream_options` | `object` | — | Tùy chọn streaming; bị ép thành `{ include_usage: true }` khi `stream: true` | | `top_p` | `number` | — | Nucleus sampling | | `frequency_penalty` | `number` | — | Hệ số phạt tần suất | | `presence_penalty` | `number` | — | Hệ số phạt sự xuất hiện | | `tools` | `array` | — | Định nghĩa function/tool calling | | `tool_choice` | `string \| object` | — | Chiến lược chọn tool | | `response_format` | `object` | — | Chế độ đầu ra có cấu trúc | | `provider` | `object` | — | Tùy chọn định tuyến/dự phòng nhà cung cấp | ### `/responses` | Trường | Kiểu | Bắt buộc | Ghi chú | | ---------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `model` | `string` | ✅ | OpenAI model ID; được phân giải và đổi thành model ID của nhà cung cấp trước khi chuyển tiếp | | `input` | `string \| array` | ✅ | Văn bản thuần hoặc các phần tử đầu vào có cấu trúc | | `instructions` | `string` | — | Văn bản chỉ dẫn cấp hệ thống | | `stream` | `boolean` | — | Bật sự kiện response dạng SSE | | `max_output_tokens` | `number` | — | Giới hạn token đầu ra | | `temperature` | `number` | — | Điều khiển lấy mẫu | | `top_p` | `number` | — | Nucleus sampling | | `tools` | `array` | — | Định nghĩa function/tool calling; được lọc với nhà cung cấp không phải gốc và chỉ giữ `type: "function"` khi áp dụng được | | `tool_choice` | `string \| object` | — | Chiến lược chọn tool; tùy thuộc mức hỗ trợ của nhà cung cấp | | `text` | `object` | — | Cấu hình đầu ra văn bản | | `store` | `boolean` | — | Lưu response ở upstream; bị loại bỏ với nhà cung cấp không phải gốc | | `metadata` | `object` | — | Metadata tùy chỉnh | | `reasoning` | `object` | — | Cấu hình suy luận; bị loại bỏ với nhà cung cấp không phải gốc | | `include` | `array` | — | Các phần response bổ sung; bị loại bỏ với nhà cung cấp không phải gốc | | `previous_response_id` | `string` | — | Liên kết tới response trước đó; bị loại bỏ với nhà cung cấp không phải gốc | | `provider` | `object` | — | Tùy chọn định tuyến/dự phòng nhà cung cấp | ### `/images/generations` | Trường | Kiểu | Bắt buộc | Ghi chú | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `model` | `string` | ✅ | Model ID có khả năng tạo hình ảnh; được phân giải và đổi thành model ID của nhà cung cấp trước khi chuyển tiếp | | `prompt` | `string` | ✅ | Văn bản prompt cho hình ảnh | | `quality` | `string` | — | Mức chất lượng | | `n` | `number` | — | Số lượng hình ảnh; dùng để ước tính khi kiểm tra trước, sau đó được chuyển tiếp nguyên vẹn | | `size` | `string` | — | Kích thước đầu ra | | `output_format` | `string` | — | Định dạng hình ảnh đầu ra | | `response_format` | `string` | — | Định dạng payload tương thích OpenAI | | `background` | `string` | — | Chế độ nền | | `style` | `string` | — | Phong cách có sẵn | | `stream` | `boolean` | — | Stream sự kiện hình ảnh khi được hỗ trợ | | `provider` | `object` | — | Tùy chọn định tuyến/dự phòng nhà cung cấp | ### `/videos` | Trường | Kiểu | Bắt buộc | Ghi chú | | --------------------------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------- | | `model` | `string` | ✅ | Model ID có khả năng tạo video; được phân giải và đổi thành model ID của nhà cung cấp trước khi chuyển tiếp | | `prompt` | `string` | ✅ | Văn bản prompt cho video (`1..32000` ký tự) | | `seconds` | \`integer \\ | string\` | — | | `size` | `string` | — | Kích thước đầu ra kiểu OpenAI. Giá trị được hỗ trợ: `720x1280`, `1280x720`, `1024x1792`, `1792x1024` | | `input_reference` | `object` | — | Đầu vào tham chiếu tùy chọn. Phải chứa chính xác một trong hai `image_url` hoặc `file_id` | | `input_reference.image_url` | `string` | — | URL HTTP/HTTPS của hình ảnh tham chiếu | | `input_reference.file_id` | `string` | — | ID tham chiếu tệp của OpenAI (hiện bị từ chối với các nhà cung cấp được định tuyến không hỗ trợ) | Ghi chú: * Endpoint này kiểm tra các trường trong request theo tham số tạo video kiểu OpenAI trước khi định tuyến. * Khi định tuyến tới OpenRouter, proxy ánh xạ tham số OpenAI sang các trường của OpenRouter: * `seconds` -> `duration` * `size` -> `resolution` + `aspect_ratio` * `input_reference.image_url` -> `input_references[]` * Các trường không được hỗ trợ cho route tương thích này sẽ trả về `400`. ### Response khi poll `GET /videos/:id` | Trường | Kiểu | Bắt buộc | Ghi chú | | --------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------ | | `id` | `string` | ✅ | ID job video | | `polling_url` | `string` | ✅ | URL endpoint để poll | | `status` | `string` | ✅ | Các trạng thái phổ biến: `pending`, `in_progress`, `completed`, `failed`, `cancelled`, `expired` | | `generation_id` | `string` | — | ID bản ghi generation (có sau khi đã xử lý) | | `unsigned_urls` | `array` | — | URL video của nhà cung cấp, nếu có | | `usage` | `object` | — | Chi tiết chi phí và mức sử dụng, nếu có | ### Response khi tải xuống `GET /videos/:id/content` | Trường | Kiểu | Bắt buộc | Ghi chú | | --------------- | --------- | -------- | ---------------------------------------- | | `id` (path) | `string` | ✅ | ID job video | | `index` (query) | `integer` | — | Chỉ số video cần tải xuống, mặc định `0` | ### `/embeddings` | Trường | Kiểu | Bắt buộc | Ghi chú | | ----------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | `string` | ✅ | Model ID có khả năng tạo embedding | | `input` | `string \| array` | ✅ | Đầu vào văn bản. Mảng chuỗi được xử lý theo lô (tối đa 128). Không thể truyền content-block đa phương thức qua trường kiểu OpenAI này — hãy dùng tương thích Gemini hoặc Anthropic. | | `dimensions` | `integer` | — | Số chiều của vector đầu ra, khi mô hình hỗ trợ số chiều thay đổi | | `encoding_format` | `string` | — | Chỉ hỗ trợ `"float"`; giá trị khác sẽ trả về `400` | Response: `{ object: "list", data: [{ object: "embedding", index, embedding: number[] }], model, usage: { prompt_tokens, total_tokens } }`. Không hỗ trợ streaming và đầu ra vector mã hóa base64. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tai-lieu-api/introduction/openai-compatibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.