{ "openapi": "3.1.0", "info": { "title": "SVG AI REST API", "version": "1.0.0", "description": "Generate new SVG designs from text or image references, or vectorize existing raster artwork. API keys are created in the signed-in API & MCP console. Generation and vectorization require paid account access and sufficient credits; website starter credits alone do not unlock API use. GET /api/v1/credits reports current access, balance and operation costs. Examples use sample identifiers, balances and SVG artwork. API calls are not idempotent; poll an accepted generation before retrying.", "contact": { "url": "https://www.svgai.org/contact" } }, "servers": [ { "url": "https://www.svgai.org", "description": "Production API; authenticated operations use the account's real credits." } ], "externalDocs": { "description": "API and MCP setup, task selection, authentication and errors", "url": "https://www.svgai.org/docs" }, "security": [ { "BearerApiKey": [] }, { "HeaderApiKey": [] } ], "tags": [ { "name": "Generation", "description": "Create or reinterpret artwork; an image reference may be redrawn." }, { "name": "Vectorization", "description": "Trace an existing raster image's shapes and colors into paths." }, { "name": "Account", "description": "Read the authenticated account's credit balance and access." } ], "paths": { "/api/v1/generate": { "post": { "operationId": "generateSvg", "tags": [ "Generation" ], "summary": "Generate SVG designs from text, an image, or both", "description": "Requires paid access and available credits. Generation can reinterpret an image; use vectorizeSvg for tracing. By default waits for results for up to approximately 240 seconds. wait=false or an unfinished wait returns HTTP 202 with a relative poll_url. Account limits apply. Requests are not idempotent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" }, "example": { "prompt": "An orange square centered on a transparent canvas", "model": "classic", "variations": 1, "transparent_background": "on", "aspect_ratio": "square", "wait": true } } } }, "responses": { "200": { "description": "Generation has completed. Example SVG and account values are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" }, "example": { "object": "svg.generation", "id": "6dce86db-468b-4bc9-b877-379a9c0894a1", "status": "completed", "model": "classic", "credits_used": 2, "credits_remaining": 18, "svgs": [ { "design_id": "8acc61ce-59b4-4562-b67c-9e4a1ca55115", "status": "completed", "svg": "" } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "202": { "description": "Generation is processing. GET the relative Location header or matching poll_url using the same account's API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" }, "example": { "object": "svg.generation", "id": "6dce86db-468b-4bc9-b877-379a9c0894a1", "status": "processing", "model": "classic", "credits_used": 2, "credits_remaining": 18, "svgs": [ { "design_id": "8acc61ce-59b4-4562-b67c-9e4a1ca55115", "status": "processing", "svg": null } ], "poll_url": "/api/v1/generations/6dce86db-468b-4bc9-b877-379a9c0894a1" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "Location": { "description": "Relative authenticated generation status URL, identical to poll_url. Present only on this accepted generation response; it does not promise completion or duplicate-safe resubmission.", "schema": { "type": "string", "format": "uri-reference" }, "example": "/api/v1/generations/6dce86db-468b-4bc9-b877-379a9c0894a1" } } }, "400": { "description": "Invalid input. Read error.message for the rejected field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "401": { "description": "Missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "message": "Missing API key. Pass it as \"Authorization: Bearer sk_svgai_...\" (create keys at https://svgai.org/dashboard/api)." } } } } }, "402": { "description": "Paid access or sufficient credits are required. Inspect error.type, upgrade_url and credit fields when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Account rate limit exceeded. error.retry_after_seconds indicates the retry delay when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying, matching error.retry_after_seconds from the existing account limiter.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "502": { "description": "Generation failed. May return a failed generation object or an error envelope; inspect the body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GenerationResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/v1/generations/{id}": { "get": { "operationId": "getGeneration", "tags": [ "Generation" ], "summary": "Read a generation owned by the authenticated account", "description": "Poll after HTTP 202. A successful HTTP response may still have processing or failed status. This response does not include model, credit fields, or poll_url.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Generation id returned by POST /api/v1/generate.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current generation status and available SVGs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationStatus" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "Invalid input. Read error.message for the rejected field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "401": { "description": "Missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "message": "Missing API key. Pass it as \"Authorization: Bearer sk_svgai_...\" (create keys at https://svgai.org/dashboard/api)." } } } } }, "404": { "description": "No generation with that id exists for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Account rate limit exceeded. error.retry_after_seconds indicates the retry delay when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying, matching error.retry_after_seconds from the existing account limiter.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/v1/vectorize": { "post": { "operationId": "vectorizeSvg", "tags": [ "Vectorization" ], "summary": "Trace an existing raster image into SVG", "description": "Requires paid access and available credits. Use for preserving the source artwork rather than redesigning it. Backgrounds are traced unless remove_background=true. If removal fails, the original image is traced and background_removed is false. Requests are not idempotent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VectorizeRequest" } } } }, "responses": { "200": { "description": "Completed vectorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VectorizationResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "Invalid input. Read error.message for the rejected field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "401": { "description": "Missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "message": "Missing API key. Pass it as \"Authorization: Bearer sk_svgai_...\" (create keys at https://svgai.org/dashboard/api)." } } } } }, "402": { "description": "Paid access or sufficient credits are required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Account rate limit exceeded. error.retry_after_seconds indicates the retry delay when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying, matching error.retry_after_seconds from the existing account limiter.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "502": { "description": "Image processing or vectorization failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/v1/credits": { "get": { "operationId": "getCredits", "tags": [ "Account" ], "summary": "Read account balance, paid API access, and operation costs", "description": "Authenticate with an API key. Check api_access before generation or vectorization. An account can have website starter credits and api_access=false.", "responses": { "200": { "description": "Current account balance and access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "401": { "description": "Missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "message": "Missing API key. Pass it as \"Authorization: Bearer sk_svgai_...\" (create keys at https://svgai.org/dashboard/api)." } } } } }, "429": { "description": "Account rate limit exceeded. error.retry_after_seconds indicates the retry delay when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying, matching error.retry_after_seconds from the existing account limiter.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } } }, "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "SVG AI API key", "description": "Create a key at https://www.svgai.org/dashboard/api. Send Authorization: Bearer YOUR_API_KEY. REST uses API keys; OAuth is available for the separately documented MCP endpoint. Never send credentials in URLs." }, "HeaderApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative API-key header. Use one authentication scheme." } }, "schemas": { "GenerateRequest": { "type": "object", "description": "At least one nonempty prompt, image or image_url is required. image and image_url cannot both be supplied. These schemas describe the recommended canonical input types; the server also normalizes some string/boolean aliases.", "properties": { "prompt": { "type": "string", "maxLength": 4000, "description": "Plain-language design brief. Optional with an image; whitespace-only text is empty." }, "image": { "type": "string", "minLength": 100, "description": "Raw base64 or an image data URL. PNG, JPEG, or WebP; up to 8 MB decoded. Do not send together with image_url." }, "image_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Publicly reachable HTTP(S) image URL. Private/reserved hosts are rejected; up to 8 MB downloaded. Do not send together with image." }, "model": { "type": "string", "enum": [ "classic", "ultra" ], "default": "classic", "description": "Generation model. Check current costs through GET /api/v1/credits." }, "variations": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1, "description": "Each variation uses credits." }, "transparent_background": { "type": "string", "enum": [ "auto", "on", "off" ], "default": "auto" }, "aspect_ratio": { "type": "string", "enum": [ "default", "square" ], "default": "default" }, "wait": { "type": "boolean", "default": true } }, "anyOf": [ { "required": [ "prompt" ], "properties": { "prompt": { "minLength": 1 } } }, { "required": [ "image" ] }, { "required": [ "image_url" ] } ], "not": { "required": [ "image", "image_url" ] } }, "VectorizeRequest": { "type": "object", "properties": { "image": { "type": "string", "minLength": 100, "description": "Raw base64 or an image data URL. PNG, JPEG, or WebP; up to 8 MB decoded. Do not send together with image_url." }, "image_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Publicly reachable HTTP(S) image URL. Private/reserved hosts are rejected; up to 8 MB downloaded. Do not send together with image." }, "remove_background": { "type": "boolean", "default": false, "description": "Attempt to remove the subject's background before tracing. Check background_removed for the actual result." } }, "oneOf": [ { "required": [ "image" ] }, { "required": [ "image_url" ] } ] }, "GeneratedSvg": { "type": "object", "required": [ "design_id", "status", "svg" ], "properties": { "design_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "processing", "failed" ] }, "svg": { "type": [ "string", "null" ], "description": "Complete SVG markup when available; null while processing or when unavailable." } } }, "GenerationStatus": { "type": "object", "required": [ "object", "id", "status", "svgs" ], "properties": { "object": { "type": "string", "const": "svg.generation" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "completed", "processing", "failed" ] }, "svgs": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedSvg" } } } }, "GenerationResponse": { "allOf": [ { "$ref": "#/components/schemas/GenerationStatus" }, { "type": "object", "required": [ "model", "credits_used", "credits_remaining" ], "properties": { "model": { "type": "string", "enum": [ "classic", "ultra" ] }, "credits_used": { "type": "number", "description": "Credits charged or reserved for this request." }, "credits_remaining": { "type": "number", "description": "Remaining account balance reported for the request." }, "poll_url": { "type": "string", "description": "Relative authenticated polling URL, present when status is processing." }, "error": { "$ref": "#/components/schemas/ApiError" } } } ] }, "VectorizationResponse": { "type": "object", "required": [ "object", "status", "svg", "background_removed", "credits_used", "credits_remaining" ], "properties": { "object": { "type": "string", "const": "svg.vectorization" }, "status": { "type": "string", "const": "completed" }, "svg": { "type": "string", "description": "Complete vectorized SVG markup." }, "background_removed": { "type": "boolean", "description": "Whether optional background removal succeeded." }, "credits_used": { "type": "number", "description": "Credits used by this request." }, "credits_remaining": { "type": "number", "description": "Remaining account balance." } } }, "CreditBalance": { "type": "object", "required": [ "object", "credits_remaining", "subscription_active", "api_access", "costs", "topup_url" ], "properties": { "object": { "type": "string", "const": "credit.balance" }, "credits_remaining": { "type": "number", "description": "Available account balance." }, "subscription_active": { "type": "boolean" }, "api_access": { "type": "boolean", "description": "Whether the account has paid access for API/MCP generation and vectorization." }, "api_access_message": { "type": "string", "description": "Explanation supplied when paid API access is unavailable." }, "costs": { "type": "object", "required": [ "generate_classic", "generate_ultra", "vectorize" ], "properties": { "generate_classic": { "type": "number", "description": "Classic generation cost per variation." }, "generate_ultra": { "type": "number", "description": "Ultra generation cost per variation." }, "vectorize": { "type": "number", "description": "Vectorization cost." } } }, "topup_url": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ApiError" } } }, "ApiError": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "permission_error", "insufficient_credits", "payment_required", "rate_limit_exceeded", "not_found", "generation_error", "server_error" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "retry_after_seconds": { "type": "number", "description": "Optional retry delay for rate_limit_exceeded." }, "credits_remaining": { "type": "number", "description": "Optional available balance for insufficient_credits." }, "credits_required": { "type": "number", "description": "Optional required credits for insufficient_credits." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Optional upgrade URL for payment_required." } } } }, "headers": { "RateLimitPolicy": { "description": "Optional observed per-user request-rate policy, shared across the account's API keys. q counts requests, not credits; w is the policy window in seconds. Omitted without a valid unexpired limiter observation. Uses the IETF HTTPAPI RateLimit draft syntax.", "schema": { "type": "string" }, "example": "\"generate\";q=20;w=60" }, "RateLimit": { "description": "Optional observed remaining request quota (r) and effective-window hint in seconds (t), calculated when responding. Concurrent requests can change available quota; this is not an acceptance, retry or full-reset guarantee. Omitted when authentication has not reached the limiter, the limiter is unavailable, or the observation is expired or invalid.", "schema": { "type": "string" }, "example": "\"generate\";r=19;t=60" } } } }