API Orkas

Tài liệu API Orkas

Kết nối các khả năng trò chuyện, tìm kiếm, giọng nói, hình ảnh và video của Orkas với công cụ riêng của bạn. Bắt đầu với Trò chuyện để tìm URL cơ sở, khóa API và tên mô hình được hầu hết ứng dụng AI sử dụng.

Tạo khóa API

Trò chuyện

Sử dụng định dạng Chat Completions tương thích OpenAI trong ứng dụng AI, công cụ dòng lệnh hoặc dịch vụ riêng của bạn.

Cài đặt kết nối

Nếu ứng dụng yêu cầu URL cơ sở, khóa API và mô hình, hãy nhập các giá trị sau.

Cài đặt	Giá trị	Mô tả
`Base URL`	`https://orkas.ai/v1`	Dùng giá trị này làm địa chỉ dịch vụ tương thích OpenAI.
`API Key`	Tạo khóa trong Tài khoản	Dán khóa vào trường khóa API của ứng dụng.
`model`	`orkas-llm-1.5`Đề xuất	Phù hợp nhất cho hỏi đáp thường ngày, viết lách và công việc văn phòng. Bao gồm DeepSeek V4.1 Flash · GPT-6 Luna · Claude-Sonnet-5 · Gemini-3.8 Flash.
`model`	`orkas-llm-1.5-pro`	Phù hợp nhất cho nghiên cứu, video, nghiên cứu và phát triển cùng các nhiệm vụ phức tạp khác. Bao gồm GPT-6 Sol · Claude Opus 5.5 · Kimi K3.

Tạo phản hồi hoàn tất trò chuyện

Điểm cuối

POST

https://orkas.ai/v1/chat/completions

Tạo phản hồi hoàn tất trò chuyện

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số nội dung yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
`model`	string	Có	`orkas-llm-1.5` hoặc `orkas-llm-1.5-pro`.
`messages`	array	Có	Các tin nhắn trong cuộc trò chuyện. Mỗi mục chứa `role` và `content`.
`stream`	boolean	Không	Trả về phản hồi dạng luồng khi là `true`. Mặc định: `false`.

Ví dụ yêu cầu

curl https://orkas.ai/v1/chat/completions \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "orkas-llm-1.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Mức sử dụng điểm tín dụng

Hạng mục tính phí	Điểm tín dụng bị trừ	Đơn vị tính phí
`orkas-llm-1.5`	Đầu vào 20–280; đọc bộ nhớ đệm 2–28; tạo bộ nhớ đệm 25–350; đầu ra 120–1,260	Trên mỗi 1M token; đơn giá chính xác phụ thuộc vào yêu cầu.
`orkas-llm-1.5-pro`	Đầu vào 140–1,000; đọc bộ nhớ đệm 14–100; tạo bộ nhớ đệm 175–1,250; đầu ra 840–4,500	Trên mỗi 1M token; đơn giá chính xác phụ thuộc vào yêu cầu.

Tìm kiếm

Tìm kiếm trên web và trả về danh sách ngắn gọn các kết quả liên quan cho ứng dụng của bạn.

Tìm kiếm trên web

Điểm cuối

POST

https://orkas.ai/v1/search

Tìm kiếm trên web

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số nội dung yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
`query`	string	Có	Văn bản tìm kiếm, tối đa 2,000 ký tự.
`max_results`	integer	Không	Số kết quả, 1–20. Mặc định: `8`.

Ví dụ yêu cầu

curl https://orkas.ai/v1/search \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest battery research","max_results":8}'

Mức sử dụng điểm tín dụng

Hạng mục tính phí	Điểm tín dụng bị trừ	Đơn vị tính phí
Tìm kiếm trên web	5.6	Mỗi yêu cầu, tối đa 20 kết quả.

Giọng nói

Chuyển văn bản thành tệp âm thanh. Chọn ID giọng nói từ danh sách bên dưới và chọn định dạng âm thanh bạn cần.

Liệt kê giọng nói

Điểm cuối

GET

https://orkas.ai/v1/audio/voices

Liệt kê giọng nói

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số yêu cầu

Điểm cuối này không có tham số yêu cầu.

Ví dụ yêu cầu

curl https://orkas.ai/v1/audio/voices \
  -H "Authorization: Bearer $ORKAS_API_KEY"

Các ID giọng nói khả dụng

ID giọng nói	Tên	Ngôn ngữ
`zh_female_vv_uranus_bigtts`	vivi 2.0	Tiếng Trung / Tiếng Anh
`saturn_zh_female_cancan_tob`	知性灿灿	Tiếng Trung
`saturn_zh_female_keainvsheng_tob`	可爱女生	Tiếng Trung
`saturn_zh_female_tiaopigongzhu_tob`	调皮公主	Tiếng Trung
`saturn_zh_male_shuanglangshaonian_tob`	爽朗少年	Tiếng Trung
`saturn_zh_male_tiancaitongzhuo_tob`	天才同桌	Tiếng Trung
`zh_female_xiaohe_uranus_bigtts`	小何	Tiếng Trung
`zh_male_m191_uranus_bigtts`	云舟	Tiếng Trung
`zh_male_taocheng_uranus_bigtts`	小天	Tiếng Trung
`en_male_tim_uranus_bigtts`	Tim	Tiếng Anh
`en_female_dacey_uranus_bigtts`	Dacey	Tiếng Anh
`en_female_stokie_uranus_bigtts`	Stokie	Tiếng Anh

Tạo giọng nói

Điểm cuối

POST

https://orkas.ai/v1/audio/speech

Tạo giọng nói

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số nội dung yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
`model`	string	Có	Dùng `orkas-tts-1`.
`input`	string	Có	Văn bản cần tổng hợp, tối đa 16,384 byte UTF-8.
`voice`	string	Có	ID giọng nói từ danh sách trên.
`language`	string	Không	Ngôn ngữ thuyết minh, chẳng hạn `zh-CN` hoặc `en`. Giọng nói đã chọn phải hỗ trợ ngôn ngữ này; nếu không, ngôn ngữ mặc định của giọng nói sẽ được dùng.
`response_format`	string	Không	`mp3`, `wav`, `opus` hoặc `ogg`. Mặc định: `mp3`.
`speed`	number	Không	Tốc độ nói từ 0.5 đến 2.0. Mặc định: `1.0`.

Ví dụ yêu cầu

curl https://orkas.ai/v1/audio/speech \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"orkas-tts-1",
    "input":"你好，欢迎使用 Orkas。",
    "voice":"zh_female_vv_uranus_bigtts",
    "language":"zh-CN",
    "response_format":"mp3",
    "speed":1.0
  }' --output speech.mp3

Mức sử dụng điểm tín dụng

Hạng mục tính phí	Điểm tín dụng bị trừ	Đơn vị tính phí
Liệt kê giọng nói	0	Mỗi yêu cầu
Tạo giọng nói	0.125	Trên mỗi giây đầu ra ước tính, làm tròn lên tối thiểu một giây.

Hình ảnh

Tạo hình ảnh từ mô tả hoặc cung cấp ảnh tham chiếu để chỉnh sửa. Mỗi yêu cầu trả về một hình ảnh.

Tạo hình ảnh

Điểm cuối

POST

https://orkas.ai/v1/images/generations

Tạo hình ảnh

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số nội dung yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
`prompt`	string	Có	Mô tả hình ảnh, tối đa 20,000 ký tự.
`size`	string	Không	`2k`, `3k`, `4k` hoặc giá trị rộng×cao được hỗ trợ. Mặc định: `2k`.
`response_format`	string	Không	`url` hoặc `b64_json`. Mặc định: `b64_json`.
`reference_images`	array	Không	Tối đa bốn URL HTTPS hoặc URL dữ liệu hình ảnh được hỗ trợ để chỉnh sửa.
`async`	boolean	Không	Trả về ID tác vụ khi là `true`. Nên dùng để tránh yêu cầu hết thời gian chờ. Mặc định: `false`.

Ví dụ yêu cầu

curl https://orkas.ai/v1/images/generations \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"A product photo on a clean studio background",
    "size":"2k",
    "response_format":"url",
    "async":true
  }'

Với yêu cầu lâu hơn: đặt "async": true. API trả về id tác vụ; dùng URL trạng thái cho đến khi kết quả sẵn sàng.

Kiểm tra trạng thái tạo

Điểm cuối

GET

https://orkas.ai/v1/images/generations/{id}

Kiểm tra trạng thái tạo

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số đường dẫn

Tham số	Loại	Bắt buộc	Mô tả
`id`	string	Có	ID tác vụ được trả về từ yêu cầu tạo.

Ví dụ yêu cầu

curl https://orkas.ai/v1/images/generations/$TASK_ID \
  -H "Authorization: Bearer $ORKAS_API_KEY"

Mức sử dụng điểm tín dụng

Hạng mục tính phí	Điểm tín dụng bị trừ	Đơn vị tính phí
Tạo hình ảnh	22	Mỗi hình ảnh được tạo
Kiểm tra trạng thái tạo	0	Mỗi yêu cầu

Video

Tạo video từ văn bản hoặc nội dung tham chiếu. Yêu cầu video chạy bất đồng bộ, vì vậy hãy dùng ID tác vụ được trả về để kiểm tra tiến độ.

Tạo video

Điểm cuối

POST

https://orkas.ai/v1/videos

Tạo video

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số nội dung yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
`prompt`	string	Có	Mô tả video cần tạo hoặc chỉnh sửa.
`duration`	integer	Không	4–15 giây. Mặc định: `5`.
`resolution`	string	Không	`480p`, `720p` hoặc `1080p`. Mặc định: `720p`.
`quality`	string	Không	`balanced` cân bằng tốc độ và mức sử dụng điểm tín dụng; `quality` ưu tiên chất lượng tạo và độ ổn định. Mặc định: `balanced`. Orkas vẫn tự động chọn mô hình video tương thích.
`ratio`	string	Không	`16:9`, `9:16`, `1:1`, `4:3`, `3:4` hoặc `21:9`. Mặc định: `16:9`.
`generate_audio`	boolean	Không	Tạo âm thanh cho video. Mặc định: `true`.
`reference_image_urls`	array	Không	Tối đa chín URL hình ảnh HTTPS công khai.
`reference_video_urls`	array	Không	Tối đa ba URL video HTTPS công khai.
`operation`	string	Không	`generate` hoặc `edit`. Chỉnh sửa cần ít nhất một video tham chiếu. Mặc định: `generate`.
`seed`	integer	Không	Giá trị khởi tạo ngẫu nhiên tùy chọn để có thể lặp lại kết quả tạo.

Ví dụ yêu cầu

curl https://orkas.ai/v1/videos \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"Camera circles a ceramic lamp in a dark studio",
    "duration":5,
    "resolution":"720p",
    "quality":"balanced",
    "ratio":"16:9",
    "generate_audio":true
  }'

Kiểm tra trạng thái video

Điểm cuối

GET

https://orkas.ai/v1/videos/{id}

Kiểm tra trạng thái video

Xác thực

Authorization: Bearer $ORKAS_API_KEY

Tham số đường dẫn

Tham số	Loại	Bắt buộc	Mô tả
`id`	string	Có	ID tác vụ được trả về từ yêu cầu tạo.

Ví dụ yêu cầu

curl https://orkas.ai/v1/videos/$TASK_ID \
  -H "Authorization: Bearer $ORKAS_API_KEY"

Mức sử dụng điểm tín dụng

Hạng mục tính phí	Điểm tín dụng bị trừ	Đơn vị tính phí
`balanced` · Văn bản hoặc hình ảnh thành video · 480p	37	Mỗi giây đầu ra
`balanced` · Văn bản hoặc hình ảnh thành video · 720p	80	Mỗi giây đầu ra
`balanced` · Văn bản hoặc hình ảnh thành video · 1080p	248	Mỗi giây đầu ra
`quality` · Văn bản hoặc hình ảnh thành video · 480p	46	Mỗi giây đầu ra
`quality` · Văn bản hoặc hình ảnh thành video · 720p	100	Mỗi giây đầu ra
`quality` · Văn bản hoặc hình ảnh thành video · 1080p	248	Mỗi giây đầu ra
`balanced` / `quality` · Chỉnh sửa video hoặc tạo video từ video tham chiếu · 480p	51	Mỗi giây đầu ra
`balanced` / `quality` · Chỉnh sửa video hoặc tạo video từ video tham chiếu · 720p	109	Mỗi giây đầu ra
`balanced` / `quality` · Chỉnh sửa video hoặc tạo video từ video tham chiếu · 1080p	271	Mỗi giây đầu ra
Kiểm tra trạng thái video	0	Mỗi yêu cầu

Bảo mật và giới hạn

Giữ kín khóa API, dùng khóa riêng cho từng ứng dụng và xóa khóa ngay nếu có khả năng bị lộ.

Gửi khóa trong tiêu đề yêu cầu Authorization: Bearer sk-orkas-….
Để nhóm mức sử dụng điểm tín dụng của một cuộc trò chuyện, hãy gửi cùng một ID không chứa thông tin có nghĩa trong X-Orkas-Conversation-Id trên các yêu cầu của cuộc trò chuyện đó. Chỉ dùng chữ cái, chữ số, - hoặc _ (tối đa 64 ký tự); không gửi tiêu đề hay nội dung tin nhắn.
Không đặt khóa trong mã trình duyệt hoặc ứng dụng di động, URL, nhật ký hay hệ thống quản lý mã nguồn.
Tạo khóa riêng cho từng ứng dụng để có thể thay thế mà không ảnh hưởng đến dịch vụ khác.
Giới hạn cho mỗi khóa: 120 yêu cầu/phút cho trò chuyện và tìm kiếm, 60 cho giọng nói, 30 yêu cầu hình ảnh và 10 yêu cầu video. Kiểm tra trạng thái cho phép 120 yêu cầu/phút.
Nếu gửi yêu cầu quá thường xuyên, API trả về HTTP 429. Đợi một lát trước khi thử lại.

Lịch sử điểm tín dụng

Mức sử dụng API được đánh dấu riêng trong lịch sử điểm tín dụng trên Orkas Web, giúp bạn phân biệt với mức sử dụng trong Orkas.