Tài liệu

Một API cho model chat, ảnh và video. Chat theo định dạng Chat Completions của OpenAI nên mọi OpenAI SDK đều dùng được, chỉ cần đổi base URL và key; ảnh theo định dạng images của OpenAI; video chạy dạng tác vụ.

Quickstart

from openai import OpenAI

client = OpenAI(base_url="https://api.apistore.cloud/v1", api_key="sk-...")

stream = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Xác thực

Gửi key trong header Authorization. Tạo key ở trang API key.

Authorization: Bearer sk-...
Base URL: https://api.apistore.cloud/v1

Có thể giới hạn key theo địa chỉ IP của bạn: ở trang API key, đặt các địa chỉ hoặc dải được phép (ví dụ 203.0.113.7 hoặc 198.51.100.0/24). Request từ nơi khác bị từ chối với lỗi 403 ip_not_allowed.

Endpoints

Mọi đường dẫn đều tính từ base URL. Mọi request đều cần API key, trừ GET /models là công khai; khi gọi kèm key, nó chỉ liệt kê các model key đó được dùng.

Model

Liệt kê các model bạn gọi được. Mỗi model có kind (chat, image hoặc video) và giá: theo token với chat, theo ảnh với ảnh, theo 1 triệu token video cho từng độ phân giải với video.

curl https://api.apistore.cloud/v1/models

Chat

POST /chat/completions nhận nguyên request của OpenAI: messages, max_tokens, temperature, top_p, stop, tools và tool_choice, response_format, stream. Trường lạ được chuyển tới model. Mọi response đều có header x-request-id; hãy gửi kèm khi liên hệ hỗ trợ.

Streaming

Đặt "stream": true để nhận server-sent events. Thêm "stream_options": {"include_usage": true} để có số token ở chunk cuối.

{
  "model": "deepseek-v4-1-flash",
  "stream": true,
  "stream_options": { "include_usage": true },
  "messages": [{ "role": "user", "content": "Hello" }]
}

Cache prompt

Phần đầu prompt lặp lại (system prompt, tài liệu dài, lịch sử chat) được nhà cung cấp cache. Token input trúng cache tự động tính giá rẻ hơn. Hãy đặt phần cố định ở đầu prompt và giữ nguyên.

Tính tiền

Mỗi request giữ trước chi phí tối đa (kích thước prompt cộng max_tokens), sau đó chỉ tính theo token thực dùng. Đặt max_tokens để tránh lỗi 402 khi số dư thấp. Request lỗi trước token đầu tiên không bị tính tiền. Ảnh tính theo số ảnh tạo ra; video tính theo token video (xem mục Video). Mọi khoản trừ đều có trong Lịch sử thanh toán ở trang Thanh toán.

Giới hạn

Giới hạn áp theo key (request mỗi phút) và theo tài khoản (request đồng thời). Một số model còn có giới hạn riêng cho mỗi tài khoản.

GET /balance trả về số tiền key còn chi được: balance_usd, credit_limit_usd và key_daily_cap_usd (null khi key không có trần chi theo ngày).

curl https://api.apistore.cloud/v1/balance -H "Authorization: Bearer sk-..."

{
  "object": "balance",
  "account": "Acme",
  "balance_usd": 42.5,
  "credit_limit_usd": 0,
  "key_daily_cap_usd": null
}

Mã lỗi

Lỗi theo định dạng OpenAI: {"error": {"message", "type", "code"}}.

Hình ảnh

Model hình ảnh nhận POST /images/generations, cùng định dạng với OpenAI. size là số điểm ảnh ("1024x1024") hoặc độ phân giải mà model hỗ trợ ("1K", "1.5K", "2K", "3K", "4K"; không phải model nào cũng có đủ) kèm aspect_ratio tùy chọn ("16:9"). Bỏ trống size để dùng cỡ chuẩn của model. output_format là "jpeg" (mặc định) hoặc "png" với model có hỗ trợ. n từ 1 đến 4. Gửi image (URL hoặc data URL, hay một danh sách) để chỉnh sửa hoặc đổi phong cách ảnh. response_format "b64_json" trả ảnh trực tiếp; "url" trả đường link dùng được trong một giờ. Tính tiền theo số ảnh tạo ra. Một số model có mức giá thứ hai, cao hơn, cho ảnh lớn (trên số điểm ảnh ghi ở model) và giá cho mỗi ảnh đầu vào, đôi khi sau một số ảnh miễn phí; usage.input_images cho biết bao nhiêu ảnh đầu vào đã bị tính tiền. Kích thước, định dạng, giới hạn ảnh đầu vào và giá của từng model có ở phần Tham chiếu model bên dưới và ở GET /models (pricing.image, pricing.image_large, pricing.image_input, và đối tượng image).

// response
{
  "id": "img_0123456789abcdef0123456789abcdef",
  "created": 1793984023,
  "model": "MODEL_NAME",
  "data": [{ "url": "https://api.apistore.cloud/v1/files/images/..." }],
  "usage": { "images": 1, "input_images": 1, "cost_usd": 0.04 }  // input_images: only when some were billed
}

Video

Model video chạy dạng tác vụ. POST /videos tạo tác vụ và trả về id ngay; gọi GET /videos/{id} vài giây một lần đến khi status là completed hoặc failed (thường 1 đến 5 phút), rồi tải về: tác vụ hoàn tất có trường url (liên kết tới tệp, hiệu lực một tuần và được làm mới mỗi lần đọc; nếu chúng tôi chưa lưu được tệp thì url là đường dẫn /v1/videos/{id}/content), và GET /videos/{id}/content luôn trả về tệp đó. Trường id của mọi phản hồi (chatcmpl-…, img_…, video_…) và request_id trong lỗi là thông tin cần gửi cho hỗ trợ.

File tham chiếu được đánh số theo từng loại, theo thứ tự bạn gửi: phần tử đầu của reference_images là ảnh 1, phần tử thứ hai là ảnh 2, video và âm thanh cũng vậy. Hãy gọi chúng như thế trong prompt, giống playground dùng [Image 1], [Video 1] và [Audio 1], ví dụ "The woman in [Image 1] walks through the street of [Video 1]". Gửi nhiều file hơn mức model nhận sẽ bị từ chối, không tự cắt bớt.

status là queued, in_progress, completed hoặc failed. Tác vụ hoàn tất có usage.video_tokens và usage.cost_usd; tác vụ lỗi không bị tính tiền và có error.code cùng error.message: generation_failed (model không tạo được video), invalid_reference (một file tham chiếu bị từ chối; thông báo nêu rõ file nào) hoặc timeout.

// GET https://api.apistore.cloud/v1/videos/video_...
{
  "id": "video_0123456789abcdef0123456789abcdef",
  "object": "video",
  "model": "MODEL_NAME",
  "status": "completed",
  "created_at": 1793984023,
  "completed_at": 1793984214,
  "prompt": "A red paper boat drifting across a calm lake at sunrise",
  "resolution": "720p",
  "ratio": "16:9",
  "seconds": 5,
  "draft": false,
  "seed": 49873,
  "url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
  "last_frame": null,
  "error": null,
  "usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}

Bản nháp (Seedance 2.5): tạo bản xem trước 480p giá rẻ trước, rồi chuyển bản ưng ý thành video chính thức 1080p với cùng seed và thiết lập.

# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'

# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "draft_id": "video_..."}'

Khi tác vụ bắt đầu, số dư bị giữ tạm chi phí ước tính: token video của (số giây video đầu vào + số giây đầu ra) theo giá của độ phân giải đó. Khi xong, bạn trả theo token thực tạo (khoảng 108K cho 5 giây 720p), phần còn lại được trả về; tác vụ lỗi không mất tiền. Trong Cài đặt bạn có thể chuyển cách tính video từ bảng giá token sang "theo USD": phí nhà cung cấp thu cho job theo giá niêm yết, trừ chiết khấu của bạn. Mỗi bản ghi tính tiền ghi rõ cách nào đã áp dụng.

Hướng dẫn theo model

Mỗi dòng model video mạnh ở đâu, giới hạn thế nào, và cách viết prompt để model làm đúng ý.

[Image 1] là người đánh cá, [Image 2] là chiếc thuyền. Phong cách phim tài liệu, ánh sáng tự nhiên.
0-6 s: toàn cảnh sát mặt nước, thuyền trôi trong sương sớm. Máy đẩy vào chậm.
6-14 s: trung cảnh, ông kéo lưới lên, từng nhịp tay. Nước nhỏ giọt từ sợi dây.
14-20 s: cận cảnh khuôn mặt, ông nhìn mẻ cá và mỉm cười.
Chỉ âm thanh môi trường: nước, gỗ, chim biển. Không phụ đề, không nhạc nền.

[Image 1] là cô gái áo khoác đỏ, [Image 2] là chợ đêm. Máy quay theo [Video 1].
Cảnh 1: toàn cảnh, cô bước vào giữa các gian hàng. Máy đẩy vào chậm.
Cảnh 2: trung cảnh, cô dừng ở gian đèn lồng và nhấc một chiếc lên. Máy cố định.
Cảnh 3: cận cảnh, ánh sáng ấm trên khuôn mặt. Cô nói {Cái này}.
Chất điện ảnh, tông ấm, nhiều chi tiết. Không phụ đề. Không tạo logo hay watermark.

MCP

Dùng các model từ AI agent qua MCP server của chúng tôi (Streamable HTTP). Thêm URL bên dưới vào Claude Code, Cursor, Windsurf, VS Code hoặc bất kỳ MCP client nào, kèm API key trong header Authorization. Lượt gọi trừ vào số dư với cùng giá như API.

URL: https://api.apistore.cloud/mcp
Authorization: Bearer sk-...

# Claude Code
claude mcp add --transport http apistore https://api.apistore.cloud/mcp \
  --header "Authorization: Bearer sk-..."

# Cursor (~/.cursor/mcp.json), Windsurf, VS Code and other MCP clients
{
  "mcpServers": {
    "apistore": {
      "url": "https://api.apistore.cloud/mcp",
      "headers": { "Authorization": "Bearer sk-..." }
    }
  }
}

Công cụ: list_models (danh sách model và giá của bạn), chat (gửi prompt hoặc messages tới model và nhận câu trả lời), create_image (tạo ảnh và nhận link), create_video (tạo video và nhận id) và get_video (trạng thái, rồi link tải file khi hoàn tất).

CLI

Lệnh apistore chạy các model chat, ảnh và video từ terminal hoặc shell script: văn bản vào, câu trả lời ra, file lưu vào nơi bạn chỉ định. Cần Node 20 trở lên.

npm install -g @apistorecloud/apistore
apistore login --key sk-...

apistore chat -m deepseek-v4-1-flash "Hello!"
apistore chat "Summarize this" < notes.md
apistore image "a red bicycle on a white wall" -o bike.png
apistore video "waves at sunset, slow pan" --resolution 720p --seconds 5

Mọi lệnh đều có --json để nhận phản hồi API thô, và key cũng có thể lấy từ APISTORE_API_KEY cho script và CI. Chạy apistore --help để xem mọi tuỳ chọn.

Danh sách model

Các model cùng loại dùng chung định dạng request. Giá tính bằng credit (1 US$ = 100 credit): trên 1 triệu token với chat và video, trên mỗi ảnh với ảnh. API trả số tiền bằng USD (cost_usd, balance_usd).

# start the task
curl https://api.apistore.cloud/v1/videos \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Seedance-2.5",
    "prompt": "A red paper boat drifting across a calm lake at sunrise",
    "resolution": "720p",
    "ratio": "16:9",
    "seconds": 5
  }'

# poll until "status": "completed", then download
curl https://api.apistore.cloud/v1/videos/video_... -H "Authorization: Bearer sk-..."
curl https://api.apistore.cloud/v1/videos/video_.../content -H "Authorization: Bearer sk-..." -o video.mp4

curl https://api.apistore.cloud/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

curl https://api.apistore.cloud/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash-economy",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# start the task
curl https://api.apistore.cloud/v1/videos \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "prompt": "A red paper boat drifting across a calm lake at sunrise",
    "resolution": "720p",
    "ratio": "16:9",
    "seconds": 5
  }'

# poll until "status": "completed", then download
curl https://api.apistore.cloud/v1/videos/video_... -H "Authorization: Bearer sk-..."
curl https://api.apistore.cloud/v1/videos/video_.../content -H "Authorization: Bearer sk-..." -o video.mp4

# start the task
curl https://api.apistore.cloud/v1/videos \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "prompt": "A red paper boat drifting across a calm lake at sunrise",
    "resolution": "720p",
    "ratio": "16:9",
    "seconds": 5
  }'

# poll until "status": "completed", then download
curl https://api.apistore.cloud/v1/videos/video_... -H "Authorization: Bearer sk-..."
curl https://api.apistore.cloud/v1/videos/video_.../content -H "Authorization: Bearer sk-..." -o video.mp4

# start the task
curl https://api.apistore.cloud/v1/videos \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "A red paper boat drifting across a calm lake at sunrise",
    "resolution": "720p",
    "ratio": "16:9",
    "seconds": 5
  }'

# poll until "status": "completed", then download
curl https://api.apistore.cloud/v1/videos/video_... -H "Authorization: Bearer sk-..."
curl https://api.apistore.cloud/v1/videos/video_.../content -H "Authorization: Bearer sk-..." -o video.mp4

curl https://api.apistore.cloud/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "prompt": "A red paper boat on a calm lake at sunrise",
    "size": "1.5K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

curl https://api.apistore.cloud/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "A red paper boat on a calm lake at sunrise",
    "size": "2K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

curl https://api.apistore.cloud/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A red paper boat on a calm lake at sunrise",
    "size": "1.5K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

curl https://api.apistore.cloud/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.5",
    "prompt": "A red paper boat on a calm lake at sunrise",
    "size": "1.5K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'