{ "openapi": "3.1.0", "info": { "title": "Upscaler API", "version": "1.0.0", "description": "Upscale video theo gói. 4K Fast: 1 credit cho video dài tối đa 35 giây. API key chỉ dùng ở máy chủ hoặc CLI." }, "servers": [ { "url": "https://up4k.io" } ], "paths": { "/api/v1/me": { "get": { "operationId": "get_api_v1_me", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "tier": { "type": "string" }, "credits": { "type": "object", "properties": { "free": { "type": "number" }, "mine": { "type": "number" } }, "required": [ "free", "mine" ] }, "max_seconds": { "type": "number" }, "daily_used": { "type": "number" }, "daily_cap": { "type": [ "number", "null" ] }, "active_count": { "type": "number" }, "max_active": { "type": "number", "description": "Existing account cap: normally 20, Creator 50" }, "rate_per_minute": { "type": "number" }, "limits": { "type": "object", "properties": { "max_seconds": { "type": "number" }, "daily_used": { "type": "number" }, "daily_cap": { "type": [ "number", "null" ] }, "active_count": { "type": "number" }, "max_active": { "type": "number", "description": "Existing account cap: normally 20, Creator 50" }, "rate_per_minute": { "type": "number" } }, "required": [ "max_seconds", "daily_used", "daily_cap", "active_count", "max_active", "rate_per_minute" ] }, "access": { "type": "object", "properties": { "unlocked": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "unlocked", "reason" ] }, "engines": { "type": "array", "description": "Các engine tài khoản được gửi trong POST /api/v1/jobs", "items": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] } }, "engines_maintenance": { "type": "array", "description": "Các engine đang bảo trì, chưa nhận job mới", "items": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] } }, "long_video": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "eligible": { "type": "boolean", "description": "true khi tài khoản được gửi video dài ngay lúc này" }, "min_seconds": { "type": "number", "description": "Video dài hơn mức này là video dài" }, "max_upload_bytes": { "type": "number", "description": "Dung lượng tối đa của một video dài; 0 khi chưa mở" }, "max_seconds": { "type": "object", "description": "Thời lượng tối đa theo từng engine, ví dụ {\"runway-4k\": 3600}" } }, "required": [ "enabled", "eligible", "min_seconds", "max_upload_bytes", "max_seconds" ], "description": "Video dài hơn min_seconds tải lên theo từng phần qua POST /api/v1/jobs/{id}/multipart" }, "api_daily_jobs": { "type": "object", "properties": { "used": { "type": "number", "description": "Số job API đã nhận trong ngày Việt Nam, kể cả job thất bại hoặc đã hủy" }, "limit": { "type": [ "number", "null" ], "description": "150 job/ngày/tài khoản; null cho Creator. Đặt lại lúc 00:00 giờ Việt Nam" } }, "required": [ "used", "limit" ] }, "consent": { "type": "object", "properties": { "terms_version": { "type": "string" }, "policy_version": { "type": "string" }, "statement": { "type": "string" }, "self_likeness_statement": { "type": "string" } }, "required": [ "terms_version", "policy_version", "statement", "self_likeness_statement" ] } }, "required": [ "email", "tier", "credits", "max_seconds", "daily_used", "daily_cap", "active_count", "max_active", "rate_per_minute", "limits", "access", "engines", "engines_maintenance", "long_video", "api_daily_jobs", "consent" ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] } } } } } } }, "/api/v1/jobs": { "post": { "operationId": "post_api_v1_jobs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same key and exact body for retries; retained for 24 hours.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "size": { "type": "number" }, "duration": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "engine": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] }, "sharpness": { "type": "string" }, "fps": { "type": "number", "description": "Average frame rate (ffprobe avg_frame_rate), never r_frame_rate; above 31 returns frame_rate_limit. Omit when unknown; the runner re-checks" }, "consent": { "type": "object", "properties": { "selfLikeness": { "type": "boolean" }, "selfLikenessConsent": { "type": "boolean", "description": "Required when selfLikeness is true", "enum": [ true ] } }, "required": [ "selfLikeness" ], "if": { "properties": { "selfLikeness": { "const": true } }, "required": [ "selfLikeness" ] }, "then": { "required": [ "selfLikenessConsent" ] } } }, "required": [ "filename", "size", "duration", "width", "height", "consent" ] } } } }, "responses": { "201": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "credits": { "type": "number" }, "charge": { "type": [ "number", "null" ] }, "kind": { "type": "string", "description": "long: upload in parts through multipart_url", "enum": [ "single", "long" ] }, "upload_url": { "type": [ "string", "null" ], "description": "Fresh presigned PUT while uploading; null on replay after upload and for long jobs" }, "upload_method": { "type": "string", "enum": [ "PUT", "multipart" ] }, "multipart_url": { "type": "string", "description": "Long jobs only: relative POST path for create, sign, complete and abort" }, "upload_headers": { "type": [ "object", "null" ], "description": "null for long jobs" }, "expires_in": { "type": "number", "description": "Seconds the upload stays open; long uploads renew on every multipart call" } }, "required": [ "id", "state", "credits", "charge", "kind", "upload_url", "upload_method", "upload_headers", "expires_in" ] } } } }, "400": { "description": "validation_error, duration_limit, resolution_limit, frame_rate_limit, source_dimensions_missing, source_short_side, source_aspect_ratio, consent_required, idempotency_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_error", "duration_limit", "resolution_limit", "frame_rate_limit", "source_dimensions_missing", "source_short_side", "source_aspect_ratio", "consent_required", "idempotency_required" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "402": { "description": "no_credits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "no_credits" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked, engine_unavailable, uploads_closed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked", "engine_unavailable", "uploads_closed" ] } } } } } ] } } } }, "409": { "description": "active_limit", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "active_limit" ] } } } } } ] } } } }, "422": { "description": "idempotency_mismatch", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_mismatch" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited, daily_limit", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited", "daily_limit" ] } } } } } ] } } } }, "503": { "description": "engine_unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "engine_unavailable" ] } } } } } ] } } } } } }, "get": { "operationId": "get_api_v1_jobs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "state": { "type": "string" }, "progress": { "type": "number", "description": "State estimate: done 100, running 50, otherwise 0" }, "queue_position": { "type": [ "number", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "duration": { "type": "number" }, "size": { "type": "number" }, "engine": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] }, "sharpness": { "type": "string" }, "credits": { "type": "number" }, "charge": { "type": [ "number", "null" ], "description": "Credit đã trừ, có thể là số thập phân; null khi dữ liệu lịch sử chưa có" }, "stage": { "type": "number" }, "created_at": { "type": "number" }, "expires_at": { "type": [ "number", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "Relative Bearer-authenticated download path only while downloadable" } }, "required": [ "id", "filename", "state", "progress", "queue_position", "error", "duration", "size", "engine", "sharpness", "credits", "charge", "stage", "created_at", "expires_at", "download_url" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "jobs", "next_cursor" ] } } } }, "400": { "description": "validation_error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_error" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}/multipart": { "post": { "operationId": "post_api_v1_jobs__id__multipart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "sign", "complete", "abort" ] }, "upload_id": { "type": "string", "description": "From create; required by sign, complete and abort" }, "parts": { "type": "array", "description": "sign: 1 to 20 part numbers such as [1,2]; complete: every part as {\"part\":1,\"etag\":\"…\"} from 1 upward, or [] when create answered completed: true" } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "create" }, "part_size": { "type": "number", "description": "create: bytes per part; the last part is shorter" }, "completed": { "type": "boolean", "description": "create: the file is already assembled; call complete with parts [] to retry admission", "enum": [ true ] }, "urls": { "type": "object", "description": "sign: part number to presigned PUT URL; read the ETag response header of each PUT" }, "ok": { "type": "boolean", "description": "complete and abort", "enum": [ true ] }, "state": { "type": "string", "description": "complete: queued once the credit is debited, or the current state on replay" } }, "required": [] } } } }, "400": { "description": "validation_error, duration_limit, resolution_limit, frame_rate_limit, source_dimensions_missing, source_short_side, source_aspect_ratio, consent_required, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_error", "duration_limit", "resolution_limit", "frame_rate_limit", "source_dimensions_missing", "source_short_side", "source_aspect_ratio", "consent_required", "conflict" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "402": { "description": "no_credits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "no_credits" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked, engine_unavailable, uploads_closed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked", "engine_unavailable", "uploads_closed" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "409": { "description": "active_limit, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "active_limit", "conflict" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited, daily_limit", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited", "daily_limit" ] } } } } } ] } } } }, "503": { "description": "engine_unavailable, storage_unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "engine_unavailable", "storage_unavailable" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}/submit": { "post": { "operationId": "post_api_v1_jobs__id__submit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "Current state on safe replay" }, "queue_position": { "type": [ "number", "null" ] } }, "required": [ "state", "queue_position" ] } } } }, "400": { "description": "validation_error, duration_limit, resolution_limit, frame_rate_limit, source_dimensions_missing, source_short_side, source_aspect_ratio, consent_required, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_error", "duration_limit", "resolution_limit", "frame_rate_limit", "source_dimensions_missing", "source_short_side", "source_aspect_ratio", "consent_required", "conflict" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "402": { "description": "no_credits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "no_credits" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked, engine_unavailable, uploads_closed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked", "engine_unavailable", "uploads_closed" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "409": { "description": "active_limit, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "active_limit", "conflict" ] } } } } } ] } } } }, "410": { "description": "expired", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "expired" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited, daily_limit", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited", "daily_limit" ] } } } } } ] } } } }, "503": { "description": "engine_unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "engine_unavailable" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}": { "get": { "operationId": "get_api_v1_jobs__id_", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "state": { "type": "string" }, "progress": { "type": "number", "description": "State estimate: done 100, running 50, otherwise 0" }, "queue_position": { "type": [ "number", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "duration": { "type": "number" }, "size": { "type": "number" }, "engine": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] }, "sharpness": { "type": "string" }, "credits": { "type": "number" }, "charge": { "type": [ "number", "null" ], "description": "Credit đã trừ, có thể là số thập phân; null khi dữ liệu lịch sử chưa có" }, "stage": { "type": "number" }, "created_at": { "type": "number" }, "expires_at": { "type": [ "number", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "Relative Bearer-authenticated download path only while downloadable" } }, "required": [ "id", "filename", "state", "progress", "queue_position", "error", "duration", "size", "engine", "sharpness", "credits", "charge", "stage", "created_at", "expires_at", "download_url" ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}/cancel": { "post": { "operationId": "post_api_v1_jobs__id__cancel", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "state": { "type": "string", "enum": [ "canceled" ] } }, "required": [ "ok", "state" ] } } } }, "400": { "description": "conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "409": { "description": "conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}/retry": { "post": { "operationId": "post_api_v1_jobs__id__retry", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Reuse the same key and exact body for retries; retained for 24 hours.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "201": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "state": { "type": "string" }, "progress": { "type": "number", "description": "State estimate: done 100, running 50, otherwise 0" }, "queue_position": { "type": [ "number", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "duration": { "type": "number" }, "size": { "type": "number" }, "engine": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] }, "sharpness": { "type": "string" }, "credits": { "type": "number" }, "charge": { "type": [ "number", "null" ], "description": "Credit đã trừ, có thể là số thập phân; null khi dữ liệu lịch sử chưa có" }, "stage": { "type": "number" }, "created_at": { "type": "number" }, "expires_at": { "type": [ "number", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "Relative Bearer-authenticated download path only while downloadable" } }, "required": [ "id", "filename", "state", "progress", "queue_position", "error", "duration", "size", "engine", "sharpness", "credits", "charge", "stage", "created_at", "expires_at", "download_url" ] } } } }, "400": { "description": "validation_error, duration_limit, resolution_limit, frame_rate_limit, source_dimensions_missing, source_short_side, source_aspect_ratio, consent_required, idempotency_required, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_error", "duration_limit", "resolution_limit", "frame_rate_limit", "source_dimensions_missing", "source_short_side", "source_aspect_ratio", "consent_required", "idempotency_required", "conflict" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "402": { "description": "no_credits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "no_credits" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked, engine_unavailable, uploads_closed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked", "engine_unavailable", "uploads_closed" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "409": { "description": "active_limit, conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "active_limit", "conflict" ] } } } } } ] } } } }, "410": { "description": "expired", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "expired" ] } } } } } ] } } } }, "422": { "description": "idempotency_mismatch", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_mismatch" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited, daily_limit", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited", "daily_limit" ] } } } } } ] } } } }, "503": { "description": "engine_unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "engine_unavailable" ] } } } } } ] } } } } } } }, "/api/v1/jobs/{id}/download": { "get": { "operationId": "get_api_v1_jobs__id__download", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thành công", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_api_key" ] } } } } } ] } } } }, "403": { "description": "account_suspended, api_locked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "account_suspended", "api_locked" ] } } } } } ] } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] } } } }, "409": { "description": "conflict", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] } } } }, "410": { "description": "expired", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "expired" ] } } } } } ] } } } }, "416": { "description": "range_not_satisfiable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "range_not_satisfiable" ] } } } } } ] } } } }, "423": { "description": "locked_for_review", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "locked_for_review" ] } } } } } ] } } } }, "426": { "description": "upgrade_required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "upgrade_required" ] } } } } } ] } } } }, "429": { "description": "rate_limited", "headers": { "Retry-After": { "description": "Số giây cần chờ khi rate_limited; với daily_limit do hạn mức API, chờ đến 00:00 giờ Việt Nam", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cx_live_..." } }, "schemas": { "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "api_locked", "account_suspended", "rate_limited", "validation_error", "engine_unavailable", "duration_limit", "resolution_limit", "frame_rate_limit", "no_credits", "daily_limit", "active_limit", "source_dimensions_missing", "source_short_side", "source_aspect_ratio", "idempotency_required", "idempotency_mismatch", "not_found", "conflict", "expired", "locked_for_review", "uploads_closed", "consent_required", "consent_outdated", "range_not_satisfiable", "upgrade_required", "storage_unavailable" ] }, "message": { "type": "string" }, "reason": { "type": "string" } } } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string", "enum": [ "job.done", "job.failed" ] }, "created_at": { "type": "number", "description": "Unix milliseconds" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "state": { "type": "string" }, "progress": { "type": "number", "description": "State estimate: done 100, running 50, otherwise 0" }, "queue_position": { "type": [ "number", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "duration": { "type": "number" }, "size": { "type": "number" }, "engine": { "type": "string", "enum": [ "runway-4k", "colab-1080p", "colab-4k-pro", "colab-4k-max", "colab-4k-ultra" ] }, "sharpness": { "type": "string" }, "credits": { "type": "number" }, "charge": { "type": [ "number", "null" ], "description": "Credit đã trừ, có thể là số thập phân; null khi dữ liệu lịch sử chưa có" }, "stage": { "type": "number" }, "created_at": { "type": "number" }, "expires_at": { "type": [ "number", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "Relative Bearer-authenticated download path only while downloadable" } }, "required": [ "id", "filename", "state", "progress", "queue_position", "error", "duration", "size", "engine", "sharpness", "credits", "charge", "stage", "created_at", "expires_at", "download_url" ] }, "reason": { "type": "string", "description": "job.failed only: input_rejected for rejected; otherwise the public v1 error code or processing_failed" } }, "required": [ "id", "event", "created_at", "job" ] } } }, "webhooks": { "jobStatus": { "post": { "security": [], "description": "At least once; up to six attempts, delayed 1m, 5m, 30m, 2h, 6h; 20 consecutive failed deliveries disable the endpoint with a bell-only notice. Saving the URL again (PUT) re-enables a disabled endpoint and restarts the failure streak; DELETE then PUT creates a fresh endpoint with a new secret.", "parameters": [ { "name": "ChugAx-Webhook-Id", "in": "header", "required": true, "description": "Delivery id, stable across retries; receivers deduplicate by this value", "schema": { "type": "string" } }, { "name": "ChugAx-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds at send time", "schema": { "type": "string" } }, { "name": "ChugAx-Signature", "in": "header", "required": true, "description": "v1=", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Đã nhận; lưu id bền vững để lọc trùng." } } } } } }