{ "openapi": "3.0.3", "info": { "title": "Vectra API", "version": "0.1.0", "description": "Asynchronous image to SVG API on the same origin as this website, using dedicated API keys. Check /capabilities for service availability. Top up in the developer console when supported by the current environment. There is no public payment API, official SDK or synchronous SVG response endpoint." }, "servers": [ { "url": "/openapi/v1", "description": "Relative to the current site origin. Set the full origin when importing into client tools." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "任务" }, { "name": "账户与能力" } ], "paths": { "/tasks": { "post": { "operationId": "createTask", "summary": "Submit a conversion task", "description": "Upload an image or submit imageUrl as JSON to create an asynchronous conversion task and reserve credits. The same idempotency key maps to the same task across all keys in an account.\n\nChoose file upload or JSON imageUrl. URLs must use HTTPS port 443, without login credentials or redirects; signed COS/OSS URLs are supported. Keep the same URL, including signature parameters, for the same idempotency key. Saved image copies are reused. Let the HTTP client generate multipart Content-Type and boundary. Each account allows up to 6 unfinished tasks, and the API platform allows 18 in total. At capacity, 429 and Retry-After are returned without creating a task or reserving credits. The response contains taskId and status, not SVG. Save the original task ID and query it; do not create duplicates.", "tags": [ "任务" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1–80 ASCII characters: [A-Za-z0-9:_-]. Each logical task is unique, and the original key is retained when the original task is retried.", "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9:_-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "imageUrl" ], "additionalProperties": false, "properties": { "imageUrl": { "type": "string", "format": "uri", "maxLength": 8192, "description": "Direct HTTPS image URL or temporary signed COS/OSS URL. Port 443 only; redirects are not followed." } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "image" ], "additionalProperties": false, "properties": { "image": { "type": "string", "format": "binary", "description": "One PNG/JPEG/WebP file, up to 10 MiB and 20 million pixels." } } } } } }, "responses": { "200": { "description": "202 Accepts new tasks and returns taskId and current status (queued means queued); Attached is the Location query address and Retry-After suggested query interval. 200 Returns the original task corresponding to the idempotent key. Both return Task JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "example": { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "status": "queued", "errorCode": null, "createdAt": "2026-10-28T02:00:00.000Z", "finishedAt": null, "expiresAt": null, "billing": { "source": "package", "state": "reserved", "reservedCents": 0, "chargedCents": null, "successOrdinal": null } } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "202": { "description": "The new task is accepted and credits are reserved, but conversion is incomplete. queued means waiting. Save taskId and poll the original task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "example": { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "status": "queued", "errorCode": null, "createdAt": "2026-10-28T02:00:00.000Z", "finishedAt": null, "expiresAt": null, "billing": { "source": "package", "state": "reserved", "reservedCents": 0, "chargedCents": null, "successOrdinal": null } } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Location": { "description": "URL for querying the original task.", "schema": { "type": "string", "example": "/openapi/v1/tasks/{taskId}" } }, "Retry-After": { "description": "Suggested delay in seconds before the first status query.", "schema": { "type": "string", "example": "3" } } } }, "400": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}": { "get": { "operationId": "getTask", "summary": "Get task status", "description": "Get the latest status, result collection deadline and reserved or settled billing for the original task.\n\nPoll every 3 seconds, or 10 seconds when queued, and stop at a terminal state. Keep querying the original task while reconciling; do not create a replacement task.", "tags": [ "任务" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tasks:read" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Submit the taskId returned by the interface.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "200 Task JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "example": { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "status": "succeeded", "errorCode": null, "createdAt": "2026-10-28T02:00:00.000Z", "finishedAt": "2026-10-28T02:01:00.000Z", "expiresAt": "2026-10-29T02:01:00.000Z", "billing": { "source": "package", "state": "consumed", "reservedCents": 0, "chargedCents": 0, "successOrdinal": "1" } } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}/result": { "get": { "operationId": "downloadResult", "summary": "Download results", "description": "Download the authenticated SVG after the task succeeds. Repeated downloads do not add successful calls or charges.\n\nThis response is not JSON. Results are retained for 24 hours after success by default; Task.expiresAt is authoritative. 410 indicates expiry.", "tags": [ "任务" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tasks:read" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The task number that belongs to the current account and has been successful.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "200 image/svg+xml binary content, Content-Disposition: attachment", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Content-Disposition": { "description": "SVG download filename.", "schema": { "type": "string", "example": "attachment; filename=\"task-id.svg\"" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}/cancel": { "post": { "operationId": "cancelTask", "summary": "Request task cancellation", "description": "Cancel a queued task or request cancellation of a dispatched task. No JSON request body is required.\n\nQueued tasks can become cancelled immediately; dispatched tasks may first become cancel_requested. Completion can race with cancellation. A succeeded result is billed as completed.", "tags": [ "任务" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Current account task number.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "200 Latest Task JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "getAccount", "summary": "Get account credits", "description": "View balance, reserved balance, available call packages, lifetime successful calls and account concurrency limits.\n\nBalances and large counts are returned as decimal strings. Divide cents by 100 only for display; do not use floating-point arithmetic for accounting.", "tags": [ "账户与能力" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "account:read" ], "responses": { "200": { "description": "200 Account JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "accountId": "6fb13245-5c30-48e4-a5c7-0bfffc34a32f", "currency": "CNY", "balanceCents": "10000", "reservedCents": "20", "availableCents": "9980", "packageAvailableCalls": "0", "packageReservedCalls": "0", "lifetimeSuccessCount": "999", "nextUnitPriceCents": 20, "maxConcurrency": 2, "activeTasks": 1, "maxPendingTasks": 6, "maxGlobalPendingTasks": 18, "walletFallback": true } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Query successful settlement records", "description": "Query successfully settled calls for this account, ordered by lifetime success ordinal, with up to 100 records per page.\n\nOnly successfully settled records are included. Query queued, failed or recovering tasks by taskId. chargedCents is in cents; consumedPackageCalls counts package calls.", "tags": [ "账户与能力" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "usage:read" ], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Optional, default 0. Without starting point, the next page is passed to the previous page nextCursor; any date filtering or limit parameter is not supported.", "schema": { "type": "string", "pattern": "^[0-9]+$", "description": "An integer represented as a decimal string to avoid client-side precision loss.", "default": "0", "maxLength": 19 } } ], "responses": { "200": { "description": "200 { items, nextCursor }; when nextCursor is null, the last page has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "items": [ { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "successOrdinal": "1001", "source": "wallet", "chargedCents": 15, "consumedPackageCalls": 0, "createdAt": "2026-10-28T02:01:00.000Z" } ], "nextCursor": null } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "400": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Get service capabilities", "description": "Check task acceptance, payment availability, input limits and result retention before integration. No conversion charge is incurred.\n\nDo not create tasks when acceptsTasks=false. paymentAvailable=false means online top-ups are unavailable in this environment; it does not mean existing valid account credits are lost.", "tags": [ "账户与能力" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [], "responses": { "200": { "description": "200 Capabilities JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" }, "example": { "version": "v1", "acceptsTasks": false, "paymentAvailable": false, "formats": [ "png", "jpeg", "webp" ], "inputMethods": [ "multipart", "https-url" ], "maxFileBytes": 10485760, "maxInputPixels": 20000000, "processingMaxEdge": 4096, "processingMaxPixels": 3145728, "maxConcurrency": 2, "maxPendingTasks": 6, "maxGlobalPendingTasks": 18, "resultRetentionSeconds": 86400 } } }, "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } } }, "401": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } }, "Retry-After": { "description": "Suggested wait in seconds. Typically 60 for per-minute limits and 3 for input concurrency limits; follow the response value.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed. Handle according to the HTTP status and error.code; not every error is retryable.", "headers": { "X-Request-Id": { "description": "Application request ID; may be omitted for gateway errors.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Authenticated responses must not be stored in public caches.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A key starting with vk_live_, created in the console. Store it only on your own server. Website cookies are not API credentials." } }, "schemas": { "Task": { "type": "object", "required": [ "taskId", "status", "errorCode", "createdAt", "finishedAt", "expiresAt", "billing" ], "properties": { "taskId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "reconciling", "cancel_requested", "succeeded", "failed", "cancelled", "expired" ] }, "errorCode": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "billing": { "$ref": "#/components/schemas/Billing" } }, "example": { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "status": "queued", "errorCode": null, "createdAt": "2026-10-28T02:00:00.000Z", "finishedAt": null, "expiresAt": null, "billing": { "source": "package", "state": "reserved", "reservedCents": 0, "chargedCents": null, "successOrdinal": null } } }, "Billing": { "type": "object", "required": [ "source", "state", "reservedCents", "chargedCents", "successOrdinal" ], "properties": { "source": { "type": "string", "enum": [ "package", "wallet" ] }, "state": { "type": "string", "enum": [ "reserved", "consumed", "released" ] }, "reservedCents": { "type": "integer", "minimum": 0, "description": "Reserved amount in cents; 0 for a call package." }, "chargedCents": { "type": "integer", "nullable": true, "minimum": 0, "description": "Settled cash amount in cents. Successful package calls are 0; null if not settled successfully." }, "successOrdinal": { "type": "string", "pattern": "^[0-9]+$", "description": "An integer represented as a decimal string to avoid client-side precision loss.", "nullable": true } } }, "Account": { "type": "object", "required": [ "accountId", "currency", "balanceCents", "reservedCents", "availableCents", "packageAvailableCalls", "packageReservedCalls", "lifetimeSuccessCount", "nextUnitPriceCents", "maxConcurrency", "activeTasks", "maxPendingTasks", "maxGlobalPendingTasks", "walletFallback" ], "properties": { "accountId": { "type": "string", "description": "The API billing account to which the current Key belongs." }, "currency": { "type": "string", "enum": [ "CNY" ] }, "balanceCents": { "type": "string", "pattern": "^[0-9]+$", "description": "The total balance, including the portion still reserved." }, "reservedCents": { "type": "string", "pattern": "^[0-9]+$", "description": "The balance that has been reserved by pending tasks." }, "availableCents": { "type": "string", "pattern": "^[0-9]+$", "description": "Current available balance, equal to balanceCents − reservedCents." }, "packageAvailableCalls": { "type": "string", "pattern": "^[0-9]+$", "description": "The number of times in the valid package that have not been consumed or reserved." }, "packageReservedCalls": { "type": "string", "pattern": "^[0-9]+$", "description": "The number of reserved packages, including expired package reservations that are still being processed." }, "lifetimeSuccessCount": { "type": "string", "pattern": "^[0-9]+$", "description": "The total number of historical successful calls, in-package and balance calls are accumulated together, and are not reset on a monthly basis." }, "nextUnitPriceCents": { "type": "integer", "description": "The unit price of the next balance call calculated based on the current historical number, 20 or 15 cents." }, "maxConcurrency": { "type": "integer", "description": "Account execution concurrency limit, currently 2, shared by all keys." }, "activeTasks": { "type": "integer", "description": "The number of tasks that have occupied the execution quota, including tasks that are being resumed and canceled." }, "maxPendingTasks": { "type": "integer", "description": "The upper limit of unfinished tasks for the account, which is currently 6." }, "maxGlobalPendingTasks": { "type": "integer", "description": "The upper limit of unfinished tasks on all OpenAPI platforms is currently 18." }, "walletFallback": { "type": "boolean", "description": "Whether the balance is allowed to be used after the times package is exhausted." } }, "example": { "accountId": "6fb13245-5c30-48e4-a5c7-0bfffc34a32f", "currency": "CNY", "balanceCents": "10000", "reservedCents": "20", "availableCents": "9980", "packageAvailableCalls": "0", "packageReservedCalls": "0", "lifetimeSuccessCount": "999", "nextUnitPriceCents": 20, "maxConcurrency": 2, "activeTasks": 1, "maxPendingTasks": 6, "maxGlobalPendingTasks": 18, "walletFallback": true } }, "UsageRecord": { "type": "object", "required": [ "taskId", "successOrdinal", "source", "chargedCents", "consumedPackageCalls", "createdAt" ], "properties": { "taskId": { "type": "string", "format": "uuid" }, "successOrdinal": { "type": "string", "pattern": "^[0-9]+$", "description": "An integer represented as a decimal string to avoid client-side precision loss." }, "source": { "type": "string", "enum": [ "wallet", "package" ] }, "chargedCents": { "type": "integer", "minimum": 0 }, "consumedPackageCalls": { "type": "integer", "enum": [ 0, 1 ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "Usage": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/UsageRecord" } }, "nextCursor": { "type": "string", "pattern": "^[0-9]+$", "description": "An integer represented as a decimal string to avoid client-side precision loss.", "nullable": true } }, "example": { "items": [ { "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e", "successOrdinal": "1001", "source": "wallet", "chargedCents": 15, "consumedPackageCalls": 0, "createdAt": "2026-10-28T02:01:00.000Z" } ], "nextCursor": null } }, "Capabilities": { "type": "object", "required": [ "version", "acceptsTasks", "paymentAvailable", "formats", "inputMethods", "maxFileBytes", "maxInputPixels", "processingMaxEdge", "processingMaxPixels", "maxConcurrency", "maxPendingTasks", "maxGlobalPendingTasks", "resultRetentionSeconds" ], "properties": { "version": { "type": "string", "enum": [ "v1" ] }, "acceptsTasks": { "type": "boolean" }, "paymentAvailable": { "type": "boolean" }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "png", "jpeg", "webp" ] } }, "inputMethods": { "type": "array", "items": { "type": "string", "enum": [ "multipart", "https-url" ] } }, "maxFileBytes": { "type": "integer" }, "maxInputPixels": { "type": "integer" }, "processingMaxEdge": { "type": "integer" }, "processingMaxPixels": { "type": "integer" }, "maxConcurrency": { "type": "integer" }, "maxPendingTasks": { "type": "integer" }, "maxGlobalPendingTasks": { "type": "integer" }, "resultRetentionSeconds": { "type": "integer" } }, "example": { "version": "v1", "acceptsTasks": false, "paymentAvailable": false, "formats": [ "png", "jpeg", "webp" ], "inputMethods": [ "multipart", "https-url" ], "maxFileBytes": 10485760, "maxInputPixels": 20000000, "processingMaxEdge": 4096, "processingMaxPixels": 3145728, "maxConcurrency": 2, "maxPendingTasks": 6, "maxGlobalPendingTasks": 18, "resultRetentionSeconds": 86400 } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "taskStatus": { "type": "string", "description": "Returns the terminal task status when no result will become available" }, "retryable": { "type": "boolean", "description": "False when no result will become available" } } }, "requestId": { "type": "string", "description": "Usually present for application errors; may be omitted for gateway errors." } }, "example": { "error": { "code": "API_CREDIT_INSUFFICIENT" }, "requestId": "f7d692da-01bf-48c8-bb45-28d063b3d9d0" } } } } }