Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

PHẦN 1: API DOCUMENTATION ĐẦY ĐỦ

StoryForge API v1.0

Base URL: https://api.storyforge.ai/v1 Authentication: Bearer Token (JWT)

1. AUTHENTICATION

POST /auth/register

Đăng ký tài khoản mới.Request:JSON Copy

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "Nguyễn Văn A"
}

Response (201):JSON Copy

{
  "success": true,
  "data": {
    "user_id": "usr_8f7d2a9e1b3c",
    "email": "user@example.com",
    "name": "Nguyễn Văn A",
    "subscription_tier": "free",
    "tokens_remaining": 10000,
    "created_at": "2024-01-15T08:30:00Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Codes:

  • 400: Email đã tồn tại

  • 422: Password không đủ mạnh

  • 429: Quá nhiều request đăng ký

POST /auth/login

Đăng nhập.Request:JSON Copy

Response (200):JSON Copy

POST /auth/refresh

Làm mới token.Request:JSON Copy

Response (200):JSON Copy

POST /auth/logout

Đăng xuất (vô hiệu hóa token).Headers: Authorization: Bearer {token}Response (200):JSON Copy

2. USER MANAGEMENT

GET /users/me

Lấy thông tin user hiện tại.Headers: Authorization: Bearer {token}Response (200):JSON Copy

PATCH /users/me

Cập nhật thông tin.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (200): Updated user object

POST /users/me/avatar

Upload avatar.Headers:

  • Authorization: Bearer {token}

  • Content-Type: multipart/form-data

Body: file (image, max 5MB)Response (200):JSON Copy

3. PROJECT MANAGEMENT

GET /projects

Liệt kê tất cả projects.Headers: Authorization: Bearer {token}Query Parameters:Table Copy

Param
Type
Description
Default

page

int

Trang hiện tại

1

limit

int

Số items/trang

20

status

string

Lọc theo status

all

sort_by

string

created_at, updated_at, title

updated_at

order

string

asc, desc

desc

Response (200):JSON Copy

POST /projects

Tạo project mới.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (201):JSON Copy

GET /projects/:id

Lấy chi tiết project.Headers: Authorization: Bearer {token}Response (200):JSON Copy

PATCH /projects/:id

Cập nhật project.Headers: Authorization: Bearer {token}Request:JSON Copy

Lưu ý: Không thể đổi writing_mode nếu đã bắt đầu viết.

DELETE /projects/:id

Xóa project.Headers: Authorization: Bearer {token}Response (200):JSON Copy

POST /projects/:id/duplicate

Nhân bản project.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (201): New project object

4. OUTLINE PARSING

GET /projects/:id/parse

Lấy kết quả parse outline.Headers: Authorization: Bearer {token}Response (200):JSON Copy

POST /projects/:id/parse/retry

Yêu cầu parse lại nếu lỗi.Headers: Authorization: Bearer {token}Response (202): Accepted, processing

5. WRITING ENGINE

POST /projects/:id/write

Bắt đầu quá trình viết.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (202):JSON Copy

GET /jobs/:id

Kiểm tra tiến độ writing job.Headers: Authorization: Bearer {token}Response (200):JSON Copy

POST /jobs/:id/pause

Tạm dừng job.Headers: Authorization: Bearer {token}Response (200): Updated job status

POST /jobs/:id/resume

Tiếp tục job.Headers: Authorization: Bearer {token}

POST /jobs/:id/cancel

Hủy job.Headers: Authorization: Bearer {token}Response (200):JSON Copy

6. CHAPTER MANAGEMENT

GET /chapters/:id

Lấy nội dung chapter.Headers: Authorization: Bearer {token}Query Parameters:Table Copy

Param
Type
Default

format

string

json (json, html, markdown, plain)

include_outline

boolean

false

include_revisions

boolean

false

Response (200):JSON Copy

PATCH /chapters/:id

Cập nhật chapter (manual edit).Headers: Authorization: Bearer {token}Request:JSON Copy

Response (200): Updated chapter

POST /chapters/:id/regenerate

Viết lại chapter/scene.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (202):JSON Copy

POST /chapters/:id/feedback

Gửi feedback cho AI.Headers: Authorization: Bearer {token}Request:JSON Copy

7. CONTENT SAFETY

GET /projects/:id/safety-review

Xem các cảnh cần review.Headers: Authorization: Bearer {token}Response (200):JSON Copy

POST /safety-review/:id/resolve

Giải quyết content flag.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (200): Updated chapter

8. EXPORT & DOWNLOAD

POST /projects/:id/export

Xuất project.Headers: Authorization: Bearer {token}Request:JSON Copy

Response (202):JSON Copy

GET /exports/:id/status

Kiểm tra tiến độ export.Headers: Authorization: Bearer {token}Response (200):JSON Copy

GET /download/:token

Download file (public URL với token tạm thời).Query: token từ download_urlResponse: File binary với headers:plain Copy

9. WEBSOCKET EVENTS

Connection: wss://ws.storyforge.ai/v1Authentication: Query param ?token={jwt}

Client → Server Events

Table Copy

Event
Payload
Description

subscribe_project

{ project_id }

Theo dõi project

unsubscribe_project

{ project_id }

Hủy theo dõi

ping

{}

Keep-alive

Server → Client Events

Table Copy

Event
Payload
Description

connected

{ session_id }

Kết nối thành công

project_update

{ project_id, status, progress }

Cập nhật project

chapter_complete

{ chapter_id, chapter_number, word_count }

Chapter xong

content_warning

{ review_id, chapter_id, scene_id, severity }

Cần review

job_complete

{ job_id, type, download_url? }

Job hoàn thành

error

{ code, message, details }

Lỗi

Example WebSocket Flow:JavaScript Copy

10. ERROR HANDLING

Error Response Format

JSON Copy

Error Codes

Table Copy

Code
HTTP Status
Description
Resolution

UNAUTHORIZED

401

Token hết hạn/không hợp lệ

Refresh hoặc login lại

FORBIDDEN

403

Không đủ quyền

Upgrade subscription

NOT_FOUND

404

Resource không tồn tại

Kiểm tra ID

VALIDATION_ERROR

422

Dữ liệu không hợp lệ

Kiểm tra schema

RATE_LIMITED

429

Quá nhiều request

Chờ hoặc upgrade

INSUFFICIENT_TOKENS

402

Hết tokens

Mua thêm hoặc chờ reset

AI_SERVICE_UNAVAILABLE

503

AI service đang bảo trì

Thử lại sau

CONTENT_POLICY_VIOLATION

400

Outline vi phạm chính sách

Sửa outline

FILE_TOO_LARGE

413

File > 50MB

Nén hoặc chia nhỏ

UNSUPPORTED_FORMAT

415

Định dạng không hỗ trợ

Chuyển đổi format

11. RATE LIMITING

Table Copy

Tier
Requests/minute
Concurrent jobs
Max file size

Free

30

1

10MB

Pro

120

3

50MB

Enterprise

600

10

200MB

Headers trong mọi response:plain Copy

PHẦN 2: DATABASE SCHEMA CHI TIẾT

PostgreSQL Schema

sql Copy

Redis Schema (Caching & Sessions)

plain Copy

PHẦN 3: UI/UX MOCKUP CHI TIẾT

Design System

Color Palette

css Copy

Typography Scale

Table Copy

Token
Size
Weight
Usage

display-1

48px

700

Hero titles

display-2

36px

700

Page titles

heading-1

30px

600

Section headers

heading-2

24px

600

Card titles

heading-3

20px

600

Subsection

body-large

18px

400

Lead paragraphs

body

16px

400

Main text

body-small

14px

400

Secondary text

caption

12px

500

Labels, metadata

Screen Mockups

1. LANDING PAGE

plain Copy

2. DASHBOARD

plain Copy

3. PROJECT CREATION - STEP 1: UPLOAD

plain Copy

4. PROJECT CREATION - STEP 2: CONFIGURATION

plain Copy

5. WRITING PROGRESS SCREEN

plain Copy

6. CHAPTER EDITOR

plain Copy

7. SAFETY REVIEW MODAL

plain Copy

8. EXPORT SCREEN

plain Copy

9. MOBILE RESPONSIVE

plain Copy

10. COMPONENT LIBRARY

Buttons

plain Copy

Form Elements

plain Copy

Cards

plain Copy

Feedback Components

plain Copy

Đây là bản spec đầy đủ cho ứng dụng StoryForge. Bạn cần tôi bổ sung thêm phần nào không?

PreviousTÀI LIỆU SPEC: ỨNG DỤNG VIẾT TRUYỆN AINextSPECIFICATION: ỨNG DỤNG THEO DÕI BIẾN ĐỘNG GIÁ CHỨNG KHOÁN MBS

Last updated