Hướng dẫn API

1. Chat

Model grok-4.7. Hỏi bằng chữ, hoặc gửi kèm ảnh để mô hình nhìn ảnh.

POST /chat/completions

curl /v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning": { "effort": "low" },
    "messages": [
      { "role": "user", "content": "Xin chào" }
    ]
  }'

Câu trả lời nằm ở choices[0].message.content. Muốn gửi ảnh, content là mảng có phần text và phần image_url. Lỗi quá tải hoặc lỗi máy chủ tự thử lại 3 lần. Sai câu hỏi thì không thử lại. Dán link TikTok, YouTube, Facebook, Instagram hoặc file mp4 thì máy chủ tải video tối đa 20 phút và 120 MB, tách từ 8 đến 24 khung hình rộng 720px kèm mốc thời gian, và chép lời nói 20 phút đầu. Bật tìm nguồn bằng `"search": true` để tìm cả web và X, hoặc `"search": ["web"]` / `"search": ["x"]`. Cũng nhận tool type web_search và x_search. Muốn JSON đúng khuôn thì gửi response_format type json_schema. Cũng có POST /v1/messages và POST /v1/responses.

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

2. Ảnh

Model grokimage. Không gửi ảnh gốc thì tạo mới. Có ảnh gốc thì sửa.

POST /images/generations

curl /v1/images/generations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grokimage",
    "prompt": "Tách trà trên bàn gỗ, ánh sáng cửa sổ",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "1k"
  }'

Ảnh trả về trong data[0].url hoặc data[0].b64_json. Sửa ảnh dùng cùng endpoint, hoặc POST /images/edits. Mỗi ảnh gốc tối đa 20 MB. Ảnh lớn nên gửi bằng link https, vì body base64 dễ bị cắt quanh 4,5 MB. Lỗi quá tải tự thử lại 3 lần.

{
  "model": "grokimage",
  "prompt": "Đổi nền thành cửa sổ buổi sáng",
  "image": { "url": "https://example.com/anh.jpg", "type": "image_url" }
}

3. Video

Model grokvideo. Tạo từ chữ, từ một ảnh, hoặc từ nhiều ảnh kèm chữ. Gọi xong phải hỏi lại cho đến khi xong.

POST /videos/generations

curl /v1/videos/generations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grokvideo",
    "prompt": "Người trong IMAGE_0 đi qua phòng ở IMAGE_1",
    "images": [
      "https://example.com/nguoi.jpg",
      "https://example.com/phong.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }'

Lần gọi đầu trả id và status pending. Hỏi kết quả bằng GET /videos/id đó, khoảng 4 giây một lần, đến khi status là done rồi lấy url. failed hoặc expired là lỗi. Mỗi ảnh tối đa 20 MB.

curl /v1/videos/ID -H "Authorization: Bearer $KEY"

4. Giọng

Model grokvoice. Gửi chữ, nhận file mp3.

POST /audio/speech

curl /v1/audio/speech \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grokvoice",
    "input": "Xin chào",
    "voice": "orion",
    "language": "vi"
  }' \
  --output doc.mp3

Giọng: orion, eve, ara, leo, rex, sal, luna, iris, carina, zagan, helix, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora, liora.

Ngôn ngữ: vi, auto, en, zh, ja, ko, fr, de, it, es-ES, es-MX, pt-BR, pt-PT, ru, ar-SA, ar-EG, ar-AE, hi, bn, id, tr. Tên giọng kiểu OpenAI cũng được: alloy thành eve, echo thành orion, fable thành luna, onyx thành rex, nova thành iris, shimmer thành ara.

Nghe file thành chữ: POST /audio/transcriptions hoặc POST /stt, dạng multipart, trường file. Model grokstt. Tối đa 25 MB. Có thể gửi language=vi và format=true.

curl /v1/audio/transcriptions \
  -H "Authorization: Bearer $KEY" \
  -F language=vi \
  -F format=true \
  -F file=@ghi-am.mp3

Lỗi thường gặp

GET /models liệt kê grok-4.7, grokimage, grokvideo, grokvoice. Endpoint này không bắt key.