{ "openapi": "3.1.0", "info": { "title": "XXXRouter API — Implementation contract", "version": "0.2.0-draft", "description": "Service implementation reference. The official service domain is https://xxxrouter.com; replace it with your deployment origin for local testing. The service is not yet deployed. Models start disabled and require certified routes, credentials and reviewed prices. Integration acceptance is pending. Account USD wallet with key caps. Public price overrides do not stack. Generated media files are never stored or rehosted; responses return the original HTTPS media URLs. Expiry is controlled by the original host; task reads do not renew URLs. Reference inputs use externally hosted HTTPS URLs. Temporary Playground input uploads are session-only and are not part of the public inference API." }, "servers": [ { "url": "https://xxxrouter.com", "description": "Official service domain; deployment and integration certification pending" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/models": { "get": { "summary": "List model contracts and configured availability", "operationId": "listModels", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "security": [ {}, { "BearerAuth": [] } ] } }, "/v1/models/{id}": { "get": { "summary": "Inspect model contract and effective price", "operationId": "getModel", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "404": { "description": "Model not found", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public platform model identifier without an infrastructure routing prefix.", "schema": { "type": "string", "example": "seedream-4.5" } } ], "security": [ {}, { "BearerAuth": [] } ] } }, "/v1/chat/completions": { "post": { "summary": "Text chat completion, optionally SSE", "operationId": "createChatCompletion", "responses": { "200": { "description": "JSON when stream=false; SSE completion chunks and [DONE] when stream=true. Final usage may arrive in a final event.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResult" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE data events containing JSON chat.completion.chunk, optional usage, then [DONE]. Errors after headers are stream events." } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" }, "409": { "description": "Idempotency conflict, response cache expired or unresolved synchronous request; inspect the retained request state.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } }, "502": { "description": "Upstream rejection or uncertain result; query/replay this request without creating a new paid submission.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique logical generation submission, persisted for safe replay. Same payload replays original; changed payload is 409. Never blindly resubmit after timeout.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/images/generations": { "post": { "summary": "Generate an image: declared sync 200 or async 202", "operationId": "createImage", "responses": { "200": { "description": "Synchronous image result or terminal asynchronous task replay.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ImageResult" }, { "$ref": "#/components/schemas/Task" } ] } } } }, "202": { "description": "Accepted asynchronous image task.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAccepted" } } } }, "409": { "description": "Idempotency conflict, response cache expired or unresolved synchronous request; inspect the retained request state.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } }, "422": { "description": "Unsupported parameter or policy refusal", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" }, "502": { "description": "Upstream rejection or uncertain result; query/replay this request without creating a new paid submission.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique logical generation submission, persisted for safe replay. Same payload replays original; changed payload is 409. Never blindly resubmit after timeout.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/videos/generations": { "post": { "summary": "Submit an asynchronous video task", "operationId": "createVideo", "responses": { "202": { "description": "Success", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAccepted" } } } }, "409": { "description": "Idempotency conflict, response cache expired or unresolved synchronous request; inspect the retained request state.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } }, "422": { "description": "Unsupported parameter or policy refusal", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" }, "200": { "description": "Terminal asynchronous task replay; no new paid submission.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "502": { "description": "Upstream rejection or uncertain result; query/replay this request without creating a new paid submission.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RequestState" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique logical generation submission, persisted for safe replay. Same payload replays original; changed payload is 409. Never blindly resubmit after timeout.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/tasks/{id}": { "get": { "summary": "Read an asynchronous task owned by this account", "operationId": "getTask", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "404": { "description": "No accessible task", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/key": { "get": { "summary": "Read the current key metadata without its secret", "operationId": "getCurrentKey", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "schemas": { "ErrorDetail": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] }, "Error": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ] }, "Money": { "type": "string", "pattern": "^\\d+\\.\\d{6}$", "description": "Non-negative USD decimal string with six places. Examples are illustrative; query configured prices.", "example": "0.040000" }, "Billing": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "held", "settled", "released", "reconciling" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "reserved": { "$ref": "#/components/schemas/Money" } }, "required": [ "status", "currency" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "name": { "type": "string" }, "modality": { "type": "string", "enum": [ "llm", "image", "video" ] }, "mode": { "type": "string", "enum": [ "stream", "sync", "async" ] }, "response_mode": { "type": "string", "enum": [ "stream", "sync", "async" ] }, "description": { "type": "object", "properties": { "en": { "type": "string" }, "zh-CN": { "type": "string" } }, "required": [] }, "parameters": { "type": "array", "items": { "type": "string" } }, "sizes": { "type": "array", "items": { "type": "string" } }, "supportsImage": { "type": "boolean" }, "unit": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "price": { "type": "number" }, "outputPrice": { "type": [ "number", "null" ] }, "pricing": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "price": { "$ref": "#/components/schemas/Money" }, "outputPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "currency", "price", "outputPrice" ] }, "enabled": { "type": "boolean" } }, "required": [ "id", "object", "name", "modality", "mode", "response_mode", "parameters", "pricing", "enabled" ] }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] }, "ImageInput": { "type": "object", "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "size": { "type": "string", "description": "Model-specific normalized size; Seedream 4.5 example: 2048x2048. Certify each choice before production." }, "n": { "type": "integer", "minimum": 1, "maximum": 1, "default": 1 }, "image": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Optional single reference image, only when the model supports it." } }, "required": [ "model", "prompt" ], "additionalProperties": false }, "VideoInput": { "type": "object", "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "duration": { "type": "integer", "enum": [ 5, 10 ], "default": 5 }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ], "default": "16:9" }, "image": { "type": "string", "format": "uri", "pattern": "^https://" } }, "required": [ "model", "prompt" ], "additionalProperties": false }, "Asset": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "media_type": { "type": "string", "enum": [ "image", "video" ] }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "url" ] }, "ImageResult": { "type": "object", "properties": { "request_id": { "type": "string" }, "model": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "sync" ] }, "status": { "type": "string", "enum": [ "succeeded" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "billing": { "$ref": "#/components/schemas/Billing" } }, "required": [ "request_id", "model", "response_mode", "status", "data", "billing" ], "description": "Original media URLs and billing metadata; no file upload, storage, proxy, or URL renewal." }, "TaskAccepted": { "type": "object", "properties": { "request_id": { "type": "string" }, "task_id": { "type": "string" }, "model": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "async" ] }, "status": { "type": "string", "enum": [ "queued", "submitting", "running", "unknown", "succeeded", "failed" ], "description": "Execution status is separate from billing status; unknown means the outcome requires reconciliation." }, "billing": { "$ref": "#/components/schemas/Billing" } }, "required": [ "request_id", "task_id", "model", "response_mode", "status", "billing" ] }, "Task": { "type": "object", "properties": { "task_id": { "type": "string" }, "request_id": { "type": "string" }, "model": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "async" ] }, "status": { "type": "string", "enum": [ "queued", "submitting", "running", "unknown", "succeeded", "failed" ], "description": "Execution status. Unknown outcomes use unknown while billing.status is reconciling; do not submit a replacement paid job." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "billing": { "$ref": "#/components/schemas/Billing" }, "error": { "$ref": "#/components/schemas/ErrorDetail" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "task_id", "request_id", "model", "response_mode", "status" ] }, "ChatMessage": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false }, "ChatInput": { "type": "object", "properties": { "model": { "type": "string", "example": "deepseek-v4-flash" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "minItems": 1, "maxItems": 100 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 4096, "default": 512 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 0.7 }, "stream": { "type": "boolean", "default": false }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean", "default": false } }, "required": [], "additionalProperties": false } }, "required": [ "model", "messages" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "minimum": 0 }, "completion_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ] }, "ChatResult": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "content_filter" ] } }, "required": [ "index", "message", "finish_reason" ] } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "id", "object", "model", "choices", "usage" ] }, "KeyInfo": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "mask": { "type": "string" }, "enabled": { "type": "boolean" }, "revoked": { "type": "boolean" }, "limit": { "type": [ "number", "null" ], "minimum": 0, "description": "USD cap; null means unlimited key cap. Zero permits no positive spending." }, "period": { "type": "string", "enum": [ "lifetime", "daily", "weekly", "monthly" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "models": { "type": "array", "items": { "type": "string" } }, "rpm": { "type": "integer", "minimum": 0 }, "ips": { "type": "array", "items": { "type": "string", "description": "IPv4 or IPv6 address or CIDR. An empty list imposes no IP restriction." } }, "createdAt": { "type": "string", "format": "date-time" }, "spent": { "type": "number" }, "reserved": { "type": "number" }, "lastUsed": { "type": [ "string", "null" ], "format": "date-time" }, "nextReset": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "mask", "enabled", "revoked", "limit", "period", "models", "rpm", "ips", "spent", "reserved" ] }, "RequestState": { "type": "object", "properties": { "request_id": { "type": "string" }, "model": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "sync", "async" ] }, "status": { "type": "string", "enum": [ "submitting", "running", "unknown", "succeeded", "failed" ] }, "billing": { "$ref": "#/components/schemas/Billing" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "request_id", "model", "response_mode", "status", "billing" ] } }, "responses": { "Unauthorized": { "description": "Stable error. Includes sanitized message and request ID.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientFunds": { "description": "Stable error. Includes sanitized message and request ID.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Stable error. Includes sanitized message and request ID.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate/concurrency exceeded. Retry GET safely; reconcile uncertain POST before resubmitting.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Stable error. Includes sanitized message and request ID.", "headers": { "X-Request-ID": { "description": "Platform request ID", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-log-retention": { "days": 30, "content": "metadata_only" }, "x-model-aliases": [ "seedream-4.5", "nano-banana-pro", "flux-2-pro", "kling-3.0", "deepseek-v4-flash" ] }