{"openapi":"3.1.0","info":{"title":"APIstable API preview","version":"0.1.0-preview","description":"Current implemented HTTP surface. / 当前已实现的 HTTP 接口。 Models and quote prices are illustrative. Real providers and paid generation are not connected. POST /v1/tasks and /v1/chat/completions return 503 provider_not_configured after authentication and applicable validation; no credits are reserved or charged. Live 202 acceptance, provider callbacks, SSE, idempotent task creation, and full model capability adapters remain future integration work. Website login sessions are separate from application API keys."},"servers":[{"url":"/","description":"This APIstable deployment / 当前部署"}],"tags":[{"name":"Models"},{"name":"Quotes"},{"name":"Tasks"},{"name":"Credits"},{"name":"LLM"}],"paths":{"/v1/models":{"get":{"operationId":"listModels","tags":["Models"],"summary":"List preview models / 获取预览模型","security":[],"description":"Public catalog. No API key required. Every returned model currently has live_available=false. Display names and capabilities are illustrative.","responses":{"200":{"description":"Preview model catalog","content":{"application/json":{"schema":{"type":"object","required":["object","data"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}}}}},"/v1/quotes":{"post":{"operationId":"createQuote","tags":["Quotes"],"summary":"Validate input and estimate credits / 校验与估价","security":[],"description":"Public, nonbinding preview estimate. No credits are reserved, no task is created, and no quote_id is issued. Unknown parameters are rejected. Inputs are checked against the current illustrative model catalog; full live supplier compatibility is not yet active. channel_quotes[].credits is the entire batch total for that route.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRequest"}}}},"responses":{"200":{"description":"Preview quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"validation_error, unsupported_parameter, invalid_output_count, unsupported_resolution, or unsupported_duration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"model_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"credit_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"model_unavailable or service_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tasks":{"get":{"operationId":"listTasks","tags":["Tasks"],"summary":"List stored tasks / 获取已存任务","security":[{"bearerAuth":[]}],"description":"Requires usage:read. Returns up to 200 account-owned tasks, newest first. No pagination cursor is implemented yet. This endpoint does not generate work.","responses":{"200":{"description":"Stored tasks","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"service_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTaskPreview","tags":["Tasks"],"summary":"Generation submission placeholder / 生成提交预览","security":[{"bearerAuth":[]}],"description":"Requires generations:write. Validates the request, then returns 503 provider_not_configured. No operation, reservation, or provider attempt is created. Idempotency-Key is shown for the future live contract but is not consumed by this disabled submission path. Do not treat HTTP 503 as a successful generation.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Reserved for live acceptance. No task is currently created or deduplicated by this header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRequest"}}}},"responses":{"400":{"description":"Invalid or unsupported input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"model_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"credit_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"provider_not_configured, model_unavailable, or service_unavailable. No live work is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"provider_not_configured","message":"Live model providers are not connected in this build. No credits were reserved or charged."}}}}}}}},"/v1/tasks/{id}":{"get":{"operationId":"getTask","tags":["Tasks"],"summary":"Read a stored task / 查询任务","security":[{"bearerAuth":[]}],"description":"Requires usage:read. The task must belong to the API key’s account. Response uses public snake_case fields, independent of console presentation. Real provider execution is not yet enabled.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Stored task ID / 已存任务 ID"}],"responses":{"200":{"description":"Stored task and per-item billing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found; task absent or not owned by this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"service_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balance":{"get":{"operationId":"getBalance","tags":["Credits"],"summary":"Read credit balance / 查询积分余额","security":[{"bearerAuth":[]}],"description":"Requires usage:read. Reads the real account balance; never issues trial credits or executes a payment.","responses":{"200":{"description":"Account credit balance","content":{"application/json":{"schema":{"type":"object","required":["balance_credits","reserved_credits","available_credits"],"properties":{"balance_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"reserved_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"available_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"}}}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"service_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/chat/completions":{"post":{"operationId":"chatCompletionsPreview","tags":["LLM"],"summary":"LLM placeholder / LLM 接口预留","security":[{"bearerAuth":[]}],"description":"Requires generations:write. This build only checks authentication and returns 503 provider_not_configured; it does not parse or validate a Chat Completions request and does not create a stream. The request example is the intended future compatibility surface, not full OpenAI compatibility. After visible SSE output starts, a future implementation must not switch providers and concatenate another answer.","requestBody":{"required":false,"description":"Planned payload only; live request validation is not yet connected.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"model":"nova-chat-4","messages":[{"role":"user","content":"Hello"}],"stream":true,"fallback":false}}}},"responses":{"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"provider_not_configured or service_unavailable; no model text or SSE stream is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"APIstable API key","description":"API key beginning as_. Keep on the server. Scope permissions are checked separately."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"GenerationInput":{"type":"object","additionalProperties":false,"required":["prompt"],"description":"Current preview input. Supported fields vary by modality and exact catalog model. No live provider mapping is implied.","properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000},"duration_seconds":{"type":"integer","description":"Video-only; must match the model duration list."},"resolution":{"type":"string","description":"Must match the model resolution list."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3"]},"seed":{"type":"integer","minimum":0},"generate_audio":{"type":"boolean","description":"Video only, subject to model support."},"instrumental":{"type":"boolean","description":"Music only."},"lyrics":{"type":"string","maxLength":5000,"description":"Music only."}}},"TaskRequest":{"type":"object","additionalProperties":false,"required":["model","input"],"properties":{"model":{"type":"string","minLength":1,"example":"prism-image-2"},"input":{"$ref":"#/components/schemas/GenerationInput"},"output_count":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Target result count. Images/videos accept 1–4; music and LLM must remain 1. Not a concurrency guarantee. / 目标结果数，非同时并发保证。"},"fallback":{"type":"boolean","default":false,"description":"Authorizes a higher-priced compatible official fallback after an eligible confirmed failure. Live execution is disabled in this build."},"max_credits":{"type":"integer","minimum":0,"description":"Whole-request reservation cap. Reject the entire request when max_reserved_credits exceeds it."}}},"Model":{"type":"object","required":["id","object","owned_by","modality","status","live_available","max_output_count","native_outputs"],"properties":{"id":{"type":"string"},"object":{"const":"model"},"owned_by":{"type":"string","description":"Illustrative display provider; not proof of a live integration."},"modality":{"type":"string","enum":["image","video","music","llm"]},"status":{"const":"preview"},"live_available":{"const":false},"max_output_count":{"type":"integer","enum":[1,4]},"native_outputs":{"type":"integer","minimum":1}}},"Quote":{"type":"object","required":["is_preview","model","input","output_count","estimated_credits","max_reserved_credits","channel_quotes","price_version","live_available"],"properties":{"is_preview":{"const":true},"model":{"type":"string"},"input":{"$ref":"#/components/schemas/GenerationInput"},"output_count":{"type":"integer","minimum":1,"maximum":4},"estimated_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"max_reserved_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"channel_quotes":{"type":"array","items":{"type":"object","required":["channel_type","credits"],"properties":{"channel_type":{"type":"string","enum":["third_party","official"]},"credits":{"type":"number","minimum":0,"description":"Whole-batch total using this channel. / 整批渠道总积分。"}}}},"price_version":{"type":"string"},"live_available":{"const":false}}},"Task":{"type":"object","required":["task_id","model","modality","status","output_count","fallback","created_at","duration_ms","counts","billing","items"],"properties":{"task_id":{"type":"string"},"model":{"type":"string"},"modality":{"type":"string"},"status":{"type":"string","description":"Operation status. Possible states include queued, running, falling_back, reconciliation_required, succeeded, partially_succeeded, failed, and cancelled."},"output_count":{"type":"integer","minimum":1,"maximum":4},"fallback":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"integer","minimum":0,"description":"Completed duration; currently zero for unfinished tasks."},"counts":{"type":"object","required":["succeeded","failed","cancelled","pending"],"properties":{"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}}},"billing":{"type":"object","required":["initial_reserved_credits","charged_credits","released_credits","remaining_reserved_credits"],"properties":{"initial_reserved_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"charged_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"released_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"remaining_reserved_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/GenerationItem"}}}},"GenerationItem":{"type":"object","required":["item_id","index","status","final_channel_type","charged_credits","attempts","outputs"],"properties":{"item_id":{"type":"string"},"index":{"type":"integer","minimum":0},"status":{"type":"string"},"final_channel_type":{"type":["string","null"],"description":"Selected successful route only; null for unfinished or failed items."},"charged_credits":{"type":"number","minimum":0,"description":"Credits, not USD. / 积分，非美元。"},"attempts":{"type":"array","items":{"type":"object","required":["attempt_id","channel_type","status","duration_ms"],"properties":{"attempt_id":{"type":"string"},"channel_type":{"type":"string"},"status":{"type":"string"},"duration_ms":{"type":"integer","minimum":0}}}},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/Output"}}}},"Output":{"type":"object","required":["output_id","type","status","assets","metadata","expires_at"],"properties":{"output_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"title":{"type":["string","null"]},"assets":{"type":"array","items":{"type":"object","required":["role","url"],"properties":{"role":{"type":"string"},"url":{"type":"string"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}