Một request — chuyện gì xảy ra trên content-api?

Từ lúc bạn bấm Enter trên CLI đến lúc nhận content trong tay. Bản giải thích cho user — phần kỹ thuật ở cuối trang.

Lấy API key miễn phí →Xem pricing
10 request/tháng miễn phí · không cần thẻ
Trong 1 dòng: Bạn gọi 1 API endpoint → Server xác thực + chống lạm dụng → Worker chạy 2 lượt AI (1 viết · 1 review độc lập) → Auto-quyết theo điểm chất lượng → Trả content qua webhook hoặc poll.
1. Sign up→2. Gọi API→3. Server validate→4. Writer viết→5. Reviewer chấm→6. Auto-gate→7. Bạn nhận
0. Lấy
API key
Đăng ký 1 phút — nhận key
Nhập email tại /register → check inbox → bấm link xác thực → API key hiện ra 1 lần duy nhất, copy + lưu lại.
Free tier: 10 request/tháng, không cần thẻ. Đủ để test pipeline với caption hoặc marketing post trước khi quyết định mua.
Key có dạng capi_xxx... — không phải JWT, không expire, có thể tạo nhiều key để revoke từng cái.
1. Bạn
gọi API
3 cách gọi — pick one or mix
CLI: content-agent write "AI trong HR" --type blog --tier pro
MCP (Claude Desktop / Cursor / VS Code): Gõ "viết caption về X" trong chat — Claude tự gọi tool write_content.
REST: POST https://content-apiapi-production.up.railway.app/v1/content/generate với header x-api-key.
6 content types:
caption · marketing · email · blog · article · landing
2. Server
validate
3 lớp kiểm tra — xảy ra trong < 50ms
Auth: SHA-256 hash của API key tra DB. Sai key → 401. Key hợp lệ → load user + tier.
Quota: Đếm jobs tháng này (chỉ count pending/running/completed — failed/rejected miễn phí). Hết quota → 429 với link upgrade.
Schema: Zod validate body. voice_id phải là UUID hợp lệ. Free tier locked sang caption + marketing.
Pass cả 3 → server snapshot voice_version (SHA-1 audit) → push job vào Redis queue → trả 202 + job_id + estimated_seconds.
3. Worker
chọn
độ đầu tư
Tier router — chọn model + checklist theo content type
Override bằng tier field trong body. Free tier luôn chạy basic.
Content typeDefault tierCó nghĩa là
captionbasicflash model · 1-pass · review nhẹ
marketing · emailupgradepro model · review chuẩn 6-Masters
blog · article · landingpropro model + thinking mode (CoT) · checklist 3-layer chiến lược
voice_mode = C (phân tích viral)analysisoverride checklist sang 7 nguyên tắc văn nói, bất kể tier
4. Voice
mode
Server chọn 1 trong 3 giọng — theo voice_mode bạn truyền (mặc định A)
Cùng 1 voice profile (= cùng giọng cốt lõi), nhưng 3 khung viết khác nhau — hợp với 3 mục tiêu khác nhau.
A — Kể chuyện cá nhân
Có nhân vật thật, cảm xúc thật, bài học rút ra. Như tâm sự ở quán cà phê.
vd: blog kể lần đầu pitch sản phẩm bị từ chối
B — Luận nguyên tắc
1 nguyên tắc + 1 metaphor xuyên suốt. Như giáo viên giảng bài.
vd: vì sao đặt ranh giới quan trọng cho founder
C — Phân tích viral
Hot-take reviewer: bối cảnh → nghịch lý → giải mã. Văn nói, ngang hàng.
vd: phân tích vì sao clip review đạt 50k tim
5. Pass 1
Writer
Writer pass — chỉ viết, KHÔNG tự chấm điểm
Input: system prompt = ABOUT_ME (voice cốt lõi) + skill tương ứng tier + voice_json của bạn. User message = topic + brief.
Model: DeepSeek-V4-Flash (basic) hoặc Pro (upgrade/pro). Pro tier bật thinking mode — model chạy chain-of-thought trước khi viết (~60–90s cho blog), output đậm chất logic hơn rõ rệt.
Output: draft hoàn chỉnh — đủ mở/thân/kết, đúng giọng, đúng độ dài kỳ vọng.
Voice profile + prompts ở lại server. Bạn không nhìn thấy system prompt; người khác cũng không.
6. Pass 2
Reviewer
độc lập
Reviewer pass — không thấy logic của Writer
Tại sao tách 2 AI? Reviewer phải đánh giá khách quan. Cùng 1 model viết rồi chấm sẽ "thuận tay" — tỷ lệ tự khen 8/10+ > thực tế.
Reviewer dùng checklist theo tier:
basic caption · post ngắnupgrade marketing · emailpro blog · article · landinganalysis Mode C (viral)
Reviewer trả về JSON nghiêm ngặt: verdict (APPROVE / REQUEST_CHANGES / REJECT) · voice_score 0–10 · issues[] · patches[] (replacement text cụ thể).
7. Auto
decision
gate
Server tự quyết — không cần bạn duyệt tay
3 lối đi, ngưỡng nghiêm:
APPROVE
  • Verdict = APPROVE VÀ score ≥ 8/10
  • Cả 2 điều kiện phải đúng (đề phòng reviewer "APPROVE" ở score 5/10)
  • → Draft thành content final
REQUEST_CHANGES
  • Có patches[] match được text trong draft
  • → Auto-apply patches, replaceAll → content final
  • Score giữ nguyên (không bump giả)
  • Patches không match draft → fallback REJECT
REJECT
  • Verdict = REJECT, hoặc reviewer trả JSON sai format
  • → Status = rejected, KHÔNG tính vào quota
  • Bạn xem issues[] rồi retry với prompt tốt hơn
8. Bạn
nhận
content
2 cách nhận — chọn theo workflow của bạn
Polling: GET /v1/content/:job_id mỗi 3–5s đến khi status = completed. CLI và MCP làm tự động.
Webhook: Truyền webhook URL khi tạo job. Server POST kết quả về URL của bạn ngay khi xong. Header X-Content-Signature: sha256=... (HMAC) để bạn verify origin. Retry 3 lần exponential backoff.
Response JSON:{ content, quality_score, voice_version, tier, voice_mode, review_report, generated_at }
voice_version snapshot SHA-1 lưu kèm job → audit trail không bị vỡ khi bạn update voice sau này.
🔒

Voice không bao giờ rời server

System prompt, writing samples, hard rules — tất cả ở server. Không endpoint nào trả voice_json raw. IP của bạn là IP của bạn.

🎯

Two-pass quality gate

Writer + Reviewer là 2 instance độc lập với 2 system prompt khác nhau. Threshold 8/10 + AND logic — không có chuyện reviewer "APPROVE" ở score thấp.

⚡

Plug vào IDE bất kỳ

MCP work với Claude Desktop, Cursor, VS Code, Codex CLI. CLI work với mọi terminal. REST work với mọi HTTP client. 1 API key, mọi nơi.

💸

Failed jobs miễn phí

Quota chỉ tính jobs completed. Rejected hoặc failed không count — bạn chỉ trả tiền cho output dùng được, không trả cho retry.

Câu hỏi hay gặp

Một bài blog mất bao lâu?Tuỳ tier. Caption basic: ~5–15s. Marketing/email upgrade: ~20–40s. Blog/article pro với thinking mode: ~60–120s (chain-of-thought thực sự chạy trên DeepSeek-V4-Pro, không phải param suông).
Free tier có đủ để test thật không?Có. 10 request/tháng đủ để bạn thử caption (free tier hỗ trợ) + xem quality_score + đọc review_report. Nếu thích pipeline, lên Starter $19 để mở blog/article/landing.
Voice của tôi được upload thế nào?POST /v1/voices với 1–10 writing samples + hard_rules (vd: no_emoji). Server hash thành voice_version SHA-1. Mỗi generation snapshot version → audit trail. Khi bạn update voice, version mới tự bump.
Nếu reviewer chấm 7/10 thì sao?Theo gate: 7/10 không đạt threshold → status = rejected. Bạn nhận review_report.issues để biết cần fix gì. Retry với brief rõ hơn, hoặc upload voice samples chuẩn hơn. Job rejected không tính quota.
Tôi có thể tự đổi reviewer threshold không?Hiện tại chốt ở 8/10 + AND logic — đây là mặt mạnh của sản phẩm (chất lượng nhất quán). Nếu bạn cần "chấp nhận thấp hơn", gọi API với tier=basic để reviewer bớt khắt khe (checklist nhẹ hơn).
DeepSeek-V4-Pro có thực sự chạy thinking?Có — đo bằng latency: pro blog ~90s vs basic caption ~4s. Sự chênh lệch ~85s chính là chain-of-thought tokens được sinh ra trước khi viết. Latency là bằng chứng.

Tham chiếu kỹ thuật (cho dev)

REST endpointPOST /v1/content/generate · GET /v1/content/:id · POST/GET/PUT /v1/voices
MCP endpointhttps://content-apiapi-production.up.railway.app/mcp (Streamable HTTP) · 3 tools: write_content, list_voices, get_content_status
CLInpm install -g @content-agent/cli · binary content-agent
Authx-api-key header hoặc Authorization: Bearer. SHA-256 hash lưu DB, raw key chỉ hiện 1 lần khi tạo.
Voice schema{ name, samples[], hard_rules[], mode_default } → server hash thành voice_version SHA-1 (12 hex chars)
Voice modeA (storytelling) · B (principle) · C (analysis). Mode C ép checklist = analysis bất kể tier.
ModelsWriter: deepseek-v4-flash (basic) · deepseek-v4-pro (upgrade · pro). Pro tier set thinking: enabled + reasoning_effort: high.
Decision gateAPPROVE only khi verdict === "APPROVE" AND voice_score >= 8. REQUEST_CHANGES auto-patch via replaceAll. Reviewer fail → fail closed (REJECT).
QueueBullMQ trên Redis. Worker timeout 120s/job. Voice cache TTL 1h.
Webhook signatureX-Content-Signature: sha256=<hex> = HMAC-SHA256(raw_body, secret). Verify timingSafeEqual.
Webhook retry3 attempts, exponential backoff 1s · 2s · 4s. Body luôn được lưu — operators có thể replay.
Error codes400 validation · 401 auth · 403 tier · 404 not found · 429 quota · 503 queue unavailable
Audit fieldsResponse include voice_version (snapshot at generation) · quality_score · review_report · tier · voice_mode · generated_at

Sẵn sàng thử?

10 request miễn phí mỗi tháng. Không thẻ. Lấy key trong < 2 phút.

Lấy API key →