{"openapi": "3.0.3", "info": {"title": "Muse Core API", "version": "0.7.0", "description": "API key → core tự quản lý kết nối, chọn chat và queue.\n\n**Cách thử:** Authorize → nhập API key nguyên gốc (không thêm Bearer) → Try it out. POST tạo media trả job: poll status_url đến completed, rồi tải download_url bằng cùng key. Key nhập vào chỉ giữ trong bộ nhớ trang.\n\nScope ứng dụng: messages, images, videos, voices. Route Admin/Bridge yêu cầu khóa admin. Một tài khoản chạy một job, hai slot giữ chỗ. Mỗi job ảnh/video độc lập dùng chat mới; retry cùng Idempotency-Key giữ nguyên job/chat. Cùng Idempotency-Key nhưng đổi nội dung/ảnh sẽ trả 409. Tạo media theo prompt; duration/model/aspect ratio không phải tham số model được cam kết. TTS là route cũ, không thuộc lượt kiểm chứng Harbor.\n\nMulti-account: heartbeat 30 giây, offline sau 120 giây. Mỗi account ready có 2 reservation và 1 worker. Đủ 2 × ready account trả 429; không account ready trả 503. VM mới cần admin duyệt do chưa xác minh stable Muse user ID."}, "servers": [{"url": "/", "description": "Core đang mở Swagger"}], "security": [{"BearerAuth": []}], "tags": [{"name": "Messages", "description": "Hỏi đáp; có thể gửi reference_images."}, {"name": "Images", "description": "Tạo ảnh thường hoặc có ảnh tham chiếu; mỗi job độc lập dùng chat mới."}, {"name": "Videos", "description": "Tạo video thường hoặc có ảnh tham chiếu; mỗi job độc lập dùng chat mới."}, {"name": "Jobs", "description": "Theo dõi job và tải kết quả thuộc API key."}, {"name": "Status"}, {"name": "Voices", "description": "Catalog giọng hiện có, cache 5 phút."}, {"name": "Admin", "description": "Khóa admin; quản lý chat, API key và kết nối."}, {"name": "Bridge", "description": "Khóa bridge/admin; extension tự sử dụng, client không cần gọi."}, {"name": "Legacy TTS", "description": "Chưa xác minh TTS trên Harbor; không cần cho ảnh/video."}], "components": {"securitySchemes": {"BearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Nhập muse_sk_... cho API ứng dụng. Dùng khóa admin riêng cho Admin/Bridge; không nhập token Muse."}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "string"}, "error_type": {"type": "string"}}, "additionalProperties": false, "required": ["error"]}, "ReferenceImage": {"type": "object", "properties": {"mime_type": {"type": "string", "enum": ["image/png", "image/jpeg", "image/webp"]}, "filename": {"type": "string", "maxLength": 255, "description": "Tên file đơn, tối đa 255 byte UTF-8; không chứa path."}, "data_base64": {"type": "string", "format": "byte", "minLength": 4, "maxLength": 11184812, "description": "Base64 thuần của bytes ảnh, không có tiền tố data URL. MIME thật phải khớp."}}, "additionalProperties": false, "required": ["mime_type", "data_base64"], "description": "JPEG/PNG/WebP tĩnh, local tối đa 16 MP/ảnh; tổng decoded input tối đa 8 MiB."}, "GenerationRequest": {"type": "object", "properties": {"prompt": {"type": "string", "minLength": 1, "maxLength": 12000, "description": "Yêu cầu cho Muse. Không rỗng sau khi trim; giới hạn local 12.000 ký tự sau trim."}, "reference_images": {"type": "array", "maxItems": 10, "items": {"$ref": "#/components/schemas/ReferenceImage"}, "description": "Không bắt buộc. Tổng decoded ≤8 MiB, HTTP body ≤12 MiB. Không nhận URL hoặc local path."}}, "additionalProperties": false, "required": ["prompt"]}, "AddressedGenerationRequest": {"type": "object", "properties": {"prompt": {"type": "string", "minLength": 1, "maxLength": 12000, "description": "Yêu cầu cho Muse. Không rỗng sau khi trim; giới hạn local 12.000 ký tự sau trim."}, "reference_images": {"type": "array", "maxItems": 10, "items": {"$ref": "#/components/schemas/ReferenceImage"}, "description": "Không bắt buộc. Tổng decoded ≤8 MiB, HTTP body ≤12 MiB. Không nhận URL hoặc local path."}, "chat_id": {"type": "string", "format": "uuid"}}, "additionalProperties": false, "required": ["prompt", "chat_id"], "description": "Admin có thể chỉ định chat; application API key không nhận chat_id."}, "Job": {"type": "object", "properties": {"job_id": {"type": "string", "format": "uuid"}, "kind": {"type": "string", "enum": ["message", "image", "video", "voice"]}, "state": {"type": "string", "enum": ["waiting_for_slot", "queued", "cooldown", "waiting_for_connection", "waiting_for_operator", "waiting_for_browser", "preparing", "running", "downloading", "completed", "error", "uncertain", "timed_out"]}, "status_url": {"type": "string"}, "request_id": {"type": "string"}, "download_url": {"type": "string"}, "answer": {"type": "string"}, "queue_position": {"type": "integer", "nullable": true}, "bytes": {"type": "integer", "minimum": 0}, "dimensions": {"type": "array", "items": {"type": "integer"}, "minItems": 2, "maxItems": 2}, "sha256": {"type": "string"}, "mime_type": {"type": "string"}, "audio_format": {"type": "string"}, "error": {"type": "string", "nullable": true}, "note": {"type": "string", "nullable": true}, "created_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}, "submitted_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}, "completed_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}, "retry_after": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}, "usage": {"type": "object", "properties": {"estimated": {"type": "boolean", "enum": [true]}, "method": {"type": "string"}, "input_tokens_estimate": {"type": "integer"}, "image_tokens_estimate": {"type": "integer"}, "context_applicable": {"type": "boolean"}, "output_tokens_estimate": {"type": "integer", "nullable": true}, "context_tokens_before_estimate": {"type": "integer", "nullable": true}, "local_context_budget": {"type": "integer"}}, "additionalProperties": true, "description": "Ước lượng local; không phải usage/tokenizer chính thức hoặc TTL token Muse."}}, "additionalProperties": true, "required": ["job_id", "kind", "state", "status_url"], "description": "App response đã lọc thông tin nội bộ. Admin có thể thấy thêm metadata. status_url/download_url là path tương đối."}, "Status": {"type": "object", "properties": {"ready": {"type": "boolean"}, "state": {"type": "string", "enum": ["ready", "warming_up", "operator_attention_required"]}}, "additionalProperties": false, "required": ["ready", "state"]}, "Chat": {"type": "object", "properties": {"chat_id": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "muse_session_id": {"type": "string", "format": "uuid"}, "state": {"type": "string"}, "tab_id": {"type": "string", "nullable": true}, "archived": {"type": "boolean"}, "created_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}}, "additionalProperties": true, "required": ["chat_id"]}, "CreateChat": {"type": "object", "properties": {"account_id": {"type": "string", "format": "uuid", "description": "Admin: account cố định cho direct chat; bỏ qua để core chọn."}, "title": {"type": "string", "minLength": 1, "maxLength": 200, "default": "Chat mới"}, "tab_id": {"type": "string", "minLength": 1, "maxLength": 128, "description": "Cùng tab_id trả cùng chat. Không dùng tiền tố __."}}, "additionalProperties": false}, "ApiKeyConfig": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 100, "default": "Ứng dụng"}, "scopes": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["messages", "images", "videos", "voices"]}}}, "additionalProperties": false}, "ApiKeyScopes": {"type": "object", "properties": {"scopes": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["messages", "images", "videos", "voices"]}}}, "additionalProperties": false, "required": ["scopes"]}, "ApiKey": {"type": "object", "properties": {"key_id": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "scopes": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["messages", "images", "videos", "voices"]}}, "created_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây."}, "revoked_at": {"type": "number", "format": "double", "description": "Unix timestamp, giây.", "nullable": true}, "api_key": {"type": "string", "description": "Chỉ trả khi tạo key; chỉ hash được lưu trong DB."}}, "additionalProperties": true}, "Credential": {"type": "object", "properties": {"vm_id": {"type": "string", "format": "uuid"}, "auth_token": {"type": "string", "minLength": 1, "maxLength": 32768, "writeOnly": true}}, "additionalProperties": false, "required": ["vm_id", "auth_token"]}, "SessionHandoff": {"type": "object", "properties": {"credential": {"$ref": "#/components/schemas/Credential"}, "request_id": {"type": "string"}, "version": {"type": "integer"}, "source": {"type": "string"}, "origin": {"type": "string"}, "issued_at": {"type": "string"}, "workspace": {"type": "object", "properties": {}, "additionalProperties": true}}, "additionalProperties": true, "required": ["credential"]}, "BridgeTokenFailure": {"type": "object", "properties": {"request_id": {"type": "string"}, "code": {"type": "string", "enum": ["AUTH_REQUIRED", "BOOTSTRAP_MISSING", "TOKEN_MISSING", "NO_TAB", "TIMEOUT", "TOKEN_HTTP", "BOOTSTRAP_HTTP", "PAGE_REQUEST_FAILED", "EXTENSION_ERROR"]}, "status": {"type": "integer"}}, "additionalProperties": false, "required": ["request_id", "code"]}, "SpeechRequest": {"type": "object", "properties": {"voice_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,266}$", "maxLength": 267}, "text": {"type": "string", "minLength": 1, "maxLength": 12000}}, "additionalProperties": false, "required": ["voice_id", "text"]}, "SpeechClaim": {"type": "object", "properties": {"request_id": {"type": "string"}}, "additionalProperties": false, "required": ["request_id"]}, "SpeechResult": {"type": "object", "properties": {"request_id": {"type": "string"}, "ok": {"type": "boolean"}, "vm_id": {"type": "string"}, "mime_type": {"type": "string", "enum": ["audio/mpeg"]}, "data_base64": {"type": "string", "format": "byte", "maxLength": 5592408}, "code": {"type": "string"}, "status": {"type": "integer"}}, "additionalProperties": false, "required": ["request_id", "ok"]}, "VoiceCatalog": {"type": "object", "properties": {"voices": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "description": {"type": "string"}, "gender": {"type": "string"}, "accent": {"type": "string"}, "tone": {"type": "string"}}, "additionalProperties": true, "required": ["id", "name"]}}, "total": {"type": "integer", "nullable": true}, "offset": {"type": "integer"}, "has_more": {"type": "boolean", "nullable": true}}, "additionalProperties": true, "required": ["voices", "offset"]}, "Runtime": {"type": "object", "properties": {}, "additionalProperties": true, "description": "Metadata vận hành: connected, connection_state, admission, queue/pool; chỉ admin."}, "Empty": {"type": "object", "properties": {}, "additionalProperties": false}, "Workspace": {"type": "object", "properties": {"vmName": {"type": "string", "format": "uuid"}, "gatewayUrl": {"type": "string", "format": "uri"}}, "additionalProperties": false, "required": ["vmName", "gatewayUrl"]}, "BridgeRegister": {"type": "object", "properties": {"bridge_instance_id": {"type": "string", "format": "uuid"}, "workspace": {"$ref": "#/components/schemas/Workspace"}, "extension_version": {"type": "string"}}, "additionalProperties": false, "required": ["bridge_instance_id", "workspace"]}, "BridgeHeartbeat": {"type": "object", "properties": {"account_id": {"type": "string", "format": "uuid"}, "bridge_epoch": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["ok", "auth_required", "no_tab", "identity_changed", "paused"], "default": "ok"}}, "additionalProperties": false, "required": ["account_id", "bridge_epoch"]}, "BridgeTokenResult": {"type": "object", "properties": {"account_id": {"type": "string", "format": "uuid"}, "bridge_epoch": {"type": "string", "format": "uuid"}, "request_id": {"type": "string", "format": "uuid"}, "ok": {"type": "boolean"}, "credential": {"$ref": "#/components/schemas/Credential"}, "code": {"type": "string"}, "http_status": {"type": "integer"}, "issued_at": {"type": "string"}}, "additionalProperties": false, "required": ["account_id", "bridge_epoch", "request_id"]}, "BridgeBootstrap": {"type": "object", "properties": {"bridge_instance_id": {"type": "string", "format": "uuid"}, "workspace": {"$ref": "#/components/schemas/Workspace"}, "extension_version": {"type": "string"}, "bootstrap_key": {"type": "string", "minLength": 50, "maxLength": 150, "writeOnly": true}, "credential": {"$ref": "#/components/schemas/Credential"}}, "additionalProperties": false, "required": ["bridge_instance_id", "workspace", "bootstrap_key"]}}}, "paths": {"/v1/messages": {"post": {"summary": "Gửi tin nhắn", "operationId": "create_messages", "tags": ["Messages"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Application API chỉ cần prompt và ảnh tham chiếu tùy chọn. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "messages", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/GenerationRequest"}, {"$ref": "#/components/schemas/AddressedGenerationRequest"}]}, "examples": {"prompt_only": {"value": {"prompt": "Reply exactly CORE_OK."}}, "with_reference": {"value": {"prompt": "Describe the attached image.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/pool/messages": {"post": {"summary": "Gửi tin nhắn", "operationId": "pool_create_messages", "tags": ["Messages"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Alias dùng pool tự chọn chat. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "messages", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Reply exactly CORE_OK."}}, "with_reference": {"value": {"prompt": "Describe the attached image.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/images": {"post": {"summary": "Tạo ảnh", "operationId": "create_images", "tags": ["Images"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Application API chỉ cần prompt và ảnh tham chiếu tùy chọn. Mỗi job mới dùng một chat mới khi được cấp slot; retry cùng Idempotency-Key không tạo chat thêm. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "images", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/GenerationRequest"}, {"$ref": "#/components/schemas/AddressedGenerationRequest"}]}, "examples": {"prompt_only": {"value": {"prompt": "Create one photograph of a blue coffee mug on a wooden table. Return the actual image file."}}, "with_reference": {"value": {"prompt": "Use the attached reference; preserve its colors and shapes. Return the actual image file.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/pool/images": {"post": {"summary": "Tạo ảnh", "operationId": "pool_create_images", "tags": ["Images"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Alias dùng pool tự chọn chat. Mỗi job mới dùng một chat mới khi được cấp slot; retry cùng Idempotency-Key không tạo chat thêm. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "images", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Create one photograph of a blue coffee mug on a wooden table. Return the actual image file."}}, "with_reference": {"value": {"prompt": "Use the attached reference; preserve its colors and shapes. Return the actual image file.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/videos": {"post": {"summary": "Tạo video", "operationId": "create_videos", "tags": ["Videos"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Application API chỉ cần prompt và ảnh tham chiếu tùy chọn. Mỗi job mới dùng một chat mới khi được cấp slot; retry cùng Idempotency-Key không tạo chat thêm. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "videos", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/GenerationRequest"}, {"$ref": "#/components/schemas/AddressedGenerationRequest"}]}, "examples": {"prompt_only": {"value": {"prompt": "Create one short landscape video of a yellow paper boat on calm water. Return the playable MP4."}}, "with_reference": {"value": {"prompt": "Use the attached reference; preserve its colors and shapes. Return the actual playable MP4 video.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/pool/videos": {"post": {"summary": "Tạo video", "operationId": "pool_create_videos", "tags": ["Videos"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Alias dùng pool tự chọn chat. Mỗi job mới dùng một chat mới khi được cấp slot; retry cùng Idempotency-Key không tạo chat thêm. Header Idempotency-Key bắt buộc với khóa admin; application key có thể bỏ qua.", "x-required-scope": "videos", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Create one short landscape video of a yellow paper boat on calm water. Return the playable MP4."}}, "with_reference": {"value": {"prompt": "Use the attached reference; preserve its colors and shapes. Return the actual playable MP4 video.", "reference_images": [{"mime_type": "image/png", "filename": "reference.png", "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAABBElEQVR42u2ZwQ3DIAxFcZQzLNYNOkUn6RTdoIuZBei1ShNEgVAoz6fEIhFP9o9tIqpqRrbFDG4AAAAAAADMDbCWv8I6V/K4L2sFSCEAEPF5Ft6uZbgIhOht7wAh2YkGAPhPAEl29hsBabH7k+uAoAEAJu6FpFEhrgGwP1J9jGn+nEPYIgDnbHo/FB88VX1mqNNPp+1zZwtyrZAa4bHNOH9RvkIAjAggpnlnt9TeveQ6fw8QjmfhFGcXKRRM8wEZEQMwO4CU/KmPNnPfWXYzRwoB0MlIKWl1SqqXs7WK8jbT1pEiE5ehAQDGKWT32EmD3jRjJSkEAAAATPQZJQIAAABAsb0Anh1ER3QiXfwAAAAASUVORK5CYII="}]}}}}}}}}, "/v1/status": {"get": {"summary": "Trạng thái kết nối", "operationId": "getStatus", "tags": ["Status"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Status"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/jobs": {"get": {"summary": "Danh sách job của API key", "operationId": "listJobs", "tags": ["Jobs"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"jobs": {"type": "array", "items": {"$ref": "#/components/schemas/Job"}}}, "additionalProperties": false, "required": ["jobs"]}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Tối đa 100 job gần nhất. Admin có thể xem mọi job."}}, "/v1/jobs/{job_id}": {"get": {"summary": "Xem trạng thái job", "operationId": "getJob", "tags": ["Jobs"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/jobs/{job_id}/file": {"get": {"summary": "Tải file kết quả", "operationId": "downloadJobFile", "tags": ["Jobs"], "responses": {"200": {"description": "Binary file; Content-Disposition: attachment.", "content": {"image/png": {"schema": {"type": "string", "format": "binary"}}, "image/jpeg": {"schema": {"type": "string", "format": "binary"}}, "image/webp": {"schema": {"type": "string", "format": "binary"}}, "video/mp4": {"schema": {"type": "string", "format": "binary"}}, "video/webm": {"schema": {"type": "string", "format": "binary"}}, "audio/mpeg": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Cần cùng API key sở hữu job. Chỉ có file sau khi tạo/tải kết quả thành công.", "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/jobs/{job_id}/recover": {"post": {"summary": "Khôi phục kết quả đã có", "operationId": "recoverJob", "tags": ["Jobs"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Chỉ đọc history/tải kết quả; không phát lại generation. Job đang chạy trả 409. Không khôi phục bằng workspace khác.", "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}, "examples": {"empty": {"value": {}}}}}}}}, "/v1/voices": {"get": {"summary": "Danh sách giọng", "operationId": "listVoices", "tags": ["Voices"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VoiceCatalog"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "x-required-scope": "voices", "parameters": [{"name": "query", "in": "query", "schema": {"type": "string", "maxLength": 200}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 100}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}}, {"name": "gender", "in": "query", "style": "form", "explode": true, "schema": {"type": "array", "maxItems": 10, "items": {"type": "string", "enum": ["F", "M"]}}}, {"name": "accent", "in": "query", "style": "form", "explode": true, "schema": {"type": "array", "maxItems": 10, "items": {"type": "string"}}}, {"name": "tone", "in": "query", "style": "form", "explode": true, "schema": {"type": "array", "maxItems": 10, "items": {"type": "string"}}}]}}, "/health": {"get": {"summary": "Health và metadata vận hành", "operationId": "getHealth", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Runtime"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin"}}, "/v1/pool": {"get": {"summary": "Queue và hai chat slot", "operationId": "getPool", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Runtime"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin"}}, "/v1/api-keys": {"get": {"summary": "Danh sách API key metadata", "operationId": "listApiKeys", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"keys": {"type": "array", "items": {"$ref": "#/components/schemas/ApiKey"}}}, "additionalProperties": false}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Không trả raw key hoặc digest.", "x-required-role": "admin"}, "post": {"summary": "Tạo application API key", "operationId": "createApiKey", "tags": ["Admin"], "responses": {"201": {"description": "Key mới; api_key chỉ hiển thị một lần.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKey"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyConfig"}, "examples": {"application": {"value": {"name": "My application", "scopes": ["messages", "images", "videos", "voices"]}}}}}}}}, "/v1/api-keys/{key_id}/scopes": {"post": {"summary": "Đổi scopes API key", "operationId": "apiKey_scopes", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyScopes"}}}}}}, "/v1/api-keys/{key_id}/revoke": {"post": {"summary": "Thu hồi API key", "operationId": "apiKey_revoke", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}}}}}}, "/v1/chats": {"get": {"summary": "Danh sách chat", "operationId": "listChats", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"chats": {"type": "array", "items": {"$ref": "#/components/schemas/Chat"}}}, "additionalProperties": false}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin"}, "post": {"summary": "Tạo/lấy chat theo tab", "operationId": "createChat", "tags": ["Admin"], "responses": {"201": {"description": "Chat mới; Muse thread được materialize khi gửi prompt đầu tiên.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Chat"}}}}, "200": {"description": "Chat đã có cho tab_id.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Chat"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateChat"}, "examples": {"tab": {"value": {"title": "Chat của tôi", "tab_id": "browser-tab-1"}}}}}}}}, "/v1/chats/{chat_id}": {"get": {"summary": "Metadata chat", "operationId": "getChat", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Chat"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/chats/{chat_id}/messages": {"get": {"summary": "History chat", "operationId": "chat_messages", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"messages": {"type": "array", "items": {"type": "object", "properties": {}, "additionalProperties": true}}}, "additionalProperties": true}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}, "post": {"summary": "Gửi messages vào chat chỉ định", "operationId": "chat_create_messages", "tags": ["Admin"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Không dùng cho chat pool hoặc chat đã archive. Hỗ trợ reference_images giống API ứng dụng.", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Reply exactly CORE_OK."}}}}}}}}, "/v1/chats/{chat_id}/jobs": {"get": {"summary": "Job thuộc chat", "operationId": "chat_jobs", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"jobs": {"type": "array", "items": {"$ref": "#/components/schemas/Job"}}}, "additionalProperties": true}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}]}}, "/v1/chats/{chat_id}/images": {"post": {"summary": "Gửi images vào chat chỉ định", "operationId": "chat_create_images", "tags": ["Admin"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Không dùng cho chat pool hoặc chat đã archive. Hỗ trợ reference_images giống API ứng dụng.", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Create one photograph of a blue coffee mug on a wooden table. Return the actual image file."}}}}}}}}, "/v1/chats/{chat_id}/videos": {"post": {"summary": "Gửi videos vào chat chỉ định", "operationId": "chat_create_videos", "tags": ["Admin"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Body hoặc ước lượng context vượt giới hạn local.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Không dùng cho chat pool hoặc chat đã archive. Hỗ trợ reference_images giống API ứng dụng.", "x-required-role": "admin", "parameters": [{"name": "chat_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationRequest"}, "examples": {"prompt_only": {"value": {"prompt": "Create one short landscape video of a yellow paper boat on calm water. Return the playable MP4."}}}}}}}}, "/v1/bridge/token-request": {"get": {"summary": "Yêu cầu admission đang chờ", "operationId": "bridgeTokenRequest", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Extension poll; request_id null khi không cần token.", "x-required-role": "admin"}}, "/v1/muse/session": {"post": {"summary": "Nhận admission từ extension", "operationId": "acceptMuseSession", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Chỉ nhận VM đã được chọn. Token không được lưu; không gửi OTP.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SessionHandoff"}}}}}}, "/v1/bridge/token-failure": {"post": {"summary": "Báo lỗi cấp admission", "operationId": "bridgeTokenFailure", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeTokenFailure"}}}}}}, "/v1/bridge/pause": {"post": {"summary": "Dừng tự kết nối và chờ vận hành", "operationId": "pauseBridge", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Runtime"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Giữ trạng thái qua restart; job chưa gửi được giữ ở waiting_for_operator.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "enum": ["MUSE_DISCONNECTED", "OPERATOR_PAUSED"], "default": "MUSE_DISCONNECTED"}}, "additionalProperties": false}}}}}}, "/v1/bridge/resume": {"post": {"summary": "Tiếp tục bridge theo thao tác vận hành", "operationId": "resumeBridge", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Runtime"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Admin tiếp tục legacy account; bridge key tiếp tục account của chính mình sau đăng nhập, không gỡ operator pause.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Empty"}, {"$ref": "#/components/schemas/BridgeHeartbeat"}]}, "examples": {"empty": {"value": {}}}}}}}}, "/v1/connection/reconnect": {"post": {"summary": "Đóng socket và xin admission mới", "operationId": "reconnectMuse", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Runtime"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** ", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}, "examples": {"empty": {"value": {}}}}}}}}, "/v1/audio/speech": {"post": {"summary": "Tạo speech — ngoài phạm vi kiểm chứng Harbor", "operationId": "createSpeech", "tags": ["Legacy TTS"], "responses": {"202": {"description": "Job được xếp hàng. Poll status_url; không tự gửi lại prompt khi trạng thái uncertain/timed_out.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "200": {"description": "Job đã tồn tại cho cùng Idempotency-Key và cùng nội dung; không tạo thêm.", "headers": {"Idempotency-Key": {"schema": {"type": "string"}, "description": "Key đã dùng; lưu để retry cùng yêu cầu."}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}, "links": {"PollJob": {"operationId": "getJob", "parameters": {"job_id": "$response.body#/job_id"}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Async job MP3. Chưa kiểm chứng trên Harbor; VM/account có thể trả voice_unavailable.", "x-required-scope": "voices", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Giữ nguyên key khi retry cùng nội dung. App key có thể bỏ qua để core sinh request_id. Admin bắt buộc truyền. Đổi prompt/ảnh/giọng phải đổi key.", "schema": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[ -~]+$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpeechRequest"}}}}}}, "/v1/bridge/speech/claim": {"post": {"summary": "Bridge speech claim", "operationId": "bridgeSpeech_claim", "tags": ["Legacy TTS"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Legacy speech bridge; claim một lần, không tự phát lại generation.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpeechClaim"}}}}}}, "/v1/bridge/speech/result": {"post": {"summary": "Bridge speech result", "operationId": "bridgeSpeech_result", "tags": ["Legacy TTS"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Legacy speech bridge; claim một lần, không tự phát lại generation.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SpeechResult"}}}}}}, "/v1/admin/accounts": {"get": {"summary": "Account và capacity", "operationId": "listAccounts", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin"}}, "/v1/admin/bridges": {"get": {"summary": "Bridge và heartbeat", "operationId": "listBridges", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin"}}, "/v1/admin/bridge-enrollments": {"post": {"summary": "Tạo enrollment một lần, hạn 10 phút", "operationId": "enrollBridge", "tags": ["Admin"], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"account_id": {"type": "string", "format": "uuid"}}, "additionalProperties": false}}}}}}, "/v1/admin/accounts/{account_id}/approve": {"post": {"summary": "Duyệt mapping account/VM", "operationId": "approveAccount", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "parameters": [{"name": "account_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 100}}, "additionalProperties": false}}}}}}, "/v1/admin/accounts/{account_id}/rebind": {"post": {"summary": "Đổi VM khi không còn job chưa giải quyết", "operationId": "rebindAccount", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "parameters": [{"name": "account_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"workspace": {"$ref": "#/components/schemas/Workspace"}}, "additionalProperties": false, "required": ["workspace"]}}}}}}, "/v1/admin/accounts/{account_id}/pause": {"post": {"summary": "Dừng account", "operationId": "pauseAccount", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "parameters": [{"name": "account_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}}}}}}, "/v1/admin/accounts/{account_id}/resume": {"post": {"summary": "Tiếp tục account", "operationId": "resumeAccount", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "parameters": [{"name": "account_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}}}}}}, "/v1/admin/bridges/{bridge_id}/revoke": {"post": {"summary": "Thu hồi bridge", "operationId": "revokeBridge", "tags": ["Admin"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "**Chỉ khóa admin/bridge.** Dùng admin key.", "x-required-role": "admin", "parameters": [{"name": "bridge_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Empty"}}}}}}, "/v1/bridge/register": {"post": {"summary": "Đăng ký bridge và đổi enrollment lấy khóa scope riêng", "operationId": "registerBridge", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Dùng bridge key gắn đúng account; register lần đầu dùng enrollment token. Không dùng application key.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeRegister"}}}}}}, "/v1/bridge/heartbeat": {"post": {"summary": "Báo online và nhận token request nếu cần", "operationId": "heartbeatBridge", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Dùng bridge key gắn đúng account; register lần đầu dùng enrollment token. Không dùng application key.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeHeartbeat"}}}}}}, "/v1/bridge/token-result": {"post": {"summary": "Trả token hoặc lỗi theo lease/epoch", "operationId": "bridgeTokenResult", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Dùng bridge key gắn đúng account; register lần đầu dùng enrollment token. Không dùng application key.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeTokenResult"}}}}}}, "/v1/bridge/disconnect": {"post": {"summary": "Báo tắt bridge", "operationId": "disconnectBridge", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Không tìm thấy hoặc không thuộc API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Dùng bridge key gắn đúng account; register lần đầu dùng enrollment token. Không dùng application key.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeHeartbeat"}}}}}}, "/v1/bridge/bootstrap": {"post": {"summary": "Tự đăng ký bằng proof Muse, không nhập enrollment", "operationId": "bootstrapBridge", "tags": ["Bridge"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": true}}}}, "400": {"description": "Body/query không hợp lệ.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Thiếu hoặc sai Bearer API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Sai scope hoặc route yêu cầu khóa admin.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Xung đột idempotency, job chưa sẵn sàng hoặc session/workspace không phù hợp.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Queue đầy hoặc upstream đang giới hạn tần suất.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "500": {"description": "Lỗi core.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Muse không chấp nhận proof hoặc upstream không sẵn sàng.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Chỉ bật trên server remote. Key ngẫu nhiên được extension lưu trước khi gửi proof. Không có credential lần đầu trả muse_proof_required; core xác minh admission với Muse trước khi ghi identity. Không gỡ account pause/revoke.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BridgeBootstrap"}}}}, "security": []}}, "/livez": {"get": {"summary": "Liveness cho container", "operationId": "getLiveness", "tags": ["Status"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}, "version": {"type": "string"}}, "additionalProperties": false}}}}, "503": {"description": "Muse/extension chưa sẵn sàng hoặc cần người vận hành xử lý.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "security": []}}}}