{"openapi":"3.1.0","info":{"title":"Zuki Image API","version":"1.0.0","summary":"Image generation and editing API","description":"Models: `zuki-image-1.0`, `zuki-image-1.0-max`. Documentation: https://zuki.pw/docs"},"servers":[{"url":"https://zuki.pw/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your zuki API key (zk-…)"}},"schemas":{"ImageInferenceTask":{"title":"imageInference task","type":"object","properties":{"taskType":{"title":"Task Type","description":"Identifier for the type of task being performed.","type":"string","const":"imageInference"},"taskUUID":{"title":"Task UUID","description":"UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task for your API key. If omitted, the server generates one and returns it in the response.","type":"string","format":"uuid"},"model":{"title":"Model","description":"Identifier of the model to use for generation.","type":"string","enum":["zuki-image-1.0","zuki-image-1.0-max"]},"positivePrompt":{"title":"Positive Prompt","description":"Text prompt describing elements to include in the generated output.","type":"string","minLength":2,"maxLength":32000},"width":{"title":"Width","description":"Width of the generated image in pixels. Must be used together with `height`. Multiple of 16. Total area (width × height) must be between 655,360 and 8,294,400 pixels, aspect ratio between 1:3 and 3:1.","type":"integer","minimum":16,"maximum":3840,"multipleOf":16},"height":{"title":"Height","description":"Height of the generated image in pixels. Must be used together with `width`. Multiple of 16.","type":"integer","minimum":16,"maximum":3840,"multipleOf":16},"inputs":{"title":"Inputs","description":"Input assets for the task.","type":"object","properties":{"referenceImages":{"title":"Reference Images","description":"List of input images: a public URL, a Data URI, raw Base64, the `imageUUID` of one of your uploads (see Uploading images) or of a previous generation. Used for image-to-image, editing and style/subject reference.","type":"array","minItems":1,"maxItems":16,"items":{"title":"Image","type":"string","anyOf":[{"format":"uuid"},{"format":"uri"},{"pattern":"^data:image\\/[a-zA-Z]+;base64,[a-zA-Z0-9+/=]+$"},{"pattern":"^[a-zA-Z0-9+/=]+$"}]}},"maskImage":{"title":"Mask Image","description":"Image that marks which areas of the input image should be edited (URL, Data URI, Base64 or image UUID). White marks the area to edit, black is preserved. The mask is treated as guidance rather than a hard boundary. With several reference images the mask applies to the first one. Requires `inputs.referenceImages`.","type":"string","anyOf":[{"format":"uuid"},{"format":"uri"},{"pattern":"^data:image\\/[a-zA-Z]+;base64,[a-zA-Z0-9+/=]+$"},{"pattern":"^[a-zA-Z0-9+/=]+$"}]}},"additionalProperties":false},"settings":{"title":"Settings","description":"Global inference settings.","type":"object","properties":{"quality":{"title":"Quality","description":"Image quality level. Higher quality takes longer and costs more.","type":"string","enum":["auto","max","xhigh","high","medium","low"],"default":"auto"},"background":{"title":"Background","description":"Background handling in generated images: `auto`, `opaque` (solid) or `transparent`. When `transparent`, `outputFormat` must be `PNG` or `WEBP`.","type":"string","enum":["auto","opaque","transparent"],"default":"auto"},"moderation":{"title":"Moderation","description":"Content moderation level: `auto` (standard filtering) or `low` (less restrictive).","type":"string","enum":["auto","low"],"default":"auto"}},"additionalProperties":false},"numberResults":{"title":"Number of Results","description":"Number of images to generate. Each result uses a different seed, producing variations.","type":"integer","minimum":1,"maximum":20,"default":1},"outputType":{"title":"Output Type","description":"How the image is returned: `URL`, `base64Data` or `dataURI`.","type":"string","enum":["URL","base64Data","dataURI"],"default":"URL"},"outputFormat":{"title":"Output Format","description":"File format of the generated image: `JPG`, `PNG` (lossless, alpha) or `WEBP` (compact, alpha).","type":"string","enum":["JPG","PNG","WEBP"],"default":"JPG"},"outputQuality":{"title":"Output Quality","description":"Compression quality of the output file. Higher values preserve quality but increase file size.","type":"integer","minimum":20,"maximum":99,"default":95},"ttl":{"title":"TTL","description":"Time-to-live in seconds for the generated image URL. Only applies when `outputType` is `URL`.","type":"integer","minimum":60},"includeCost":{"title":"Include Cost","description":"Include the amount deducted from your balance in the response (`cost` field, per image).","type":"boolean","default":false},"deliveryMethod":{"title":"Delivery Method","description":"`sync` returns complete results in the response. `async` returns an immediate acknowledgment; fetch results with a `getResponse` task or receive them on `webhookURL`.","type":"string","enum":["sync","async"],"default":"sync"},"webhookURL":{"title":"Webhook URL","description":"URL that receives each result as JSON via HTTP POST as soon as it is ready. For `numberResults` > 1 every image triggers a separate call.","type":"string","format":"uri","maxLength":2048},"uploadEndpoint":{"title":"Upload Endpoint","description":"URL where every generated image is uploaded with HTTP PUT (raw binary body). Use presigned URLs for S3 / GCS / Azure / any storage.","type":"string","format":"uri","maxLength":4096},"safety":{"title":"Safety Settings","description":"Content safety checking configuration.","type":"object","properties":{"checkContent":{"title":"Check Content","description":"Enable additional content safety checking (`NSFWContent` flag in the response). Increases generation time.","type":"boolean"}},"additionalProperties":false},"advancedFeatures":{"title":"Advanced Features","description":"Advanced configuration options.","type":"object","properties":{"watermark":{"title":"Watermark","description":"Adds a text or image watermark to the generated image. Provide either `text` or `image`, not both.","type":"object","properties":{"text":{"title":"Text","description":"Watermark text.","type":"string","minLength":2,"maxLength":32},"image":{"title":"Image","description":"Watermark image (image UUID, URL, Data URI, or Base64).","type":"string","anyOf":[{"format":"uuid"},{"format":"uri"},{"pattern":"^data:image\\/[a-zA-Z]+;base64,[a-zA-Z0-9+/=]+$"},{"pattern":"^[a-zA-Z0-9+/=]+$"}]},"displayPosition":{"title":"Display Position","description":"Watermark position.","type":"string","enum":["top-left","top-center","top-right","center-left","center-center","center-right","bottom-left","bottom-center","bottom-right","tiled"]},"opacity":{"title":"Opacity","description":"Watermark opacity from 0.1 to 1.","type":"number","multipleOf":0.01,"minimum":0.1,"maximum":1},"fontColor":{"title":"Font Color","description":"Text color in hex format.","type":"string","pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"bgColor":{"title":"Background Color","description":"Background color in hex format.","type":"string","pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"}},"oneOf":[{"required":["text"]},{"required":["image"]}],"additionalProperties":false}},"additionalProperties":false}},"required":["taskType","model","positivePrompt"],"dependentRequired":{"width":["height"],"height":["width"]},"allOf":[{"if":{"properties":{"settings":{"properties":{"background":{"const":"transparent"}},"required":["background"]}},"required":["settings"]},"then":{"properties":{"outputFormat":{"enum":["PNG","WEBP"]}},"required":["outputFormat"]}},{"if":{"properties":{"inputs":{"required":["maskImage"]}},"required":["inputs"]},"then":{"properties":{"inputs":{"required":["referenceImages"]}},"required":["inputs"]}}],"additionalProperties":false},"GetResponseTask":{"type":"object","required":["taskType","taskUUID"],"properties":{"taskType":{"const":"getResponse"},"taskUUID":{"type":"string","format":"uuid"}}},"ImageResult":{"type":"object","required":["taskType","taskUUID","imageUUID"],"properties":{"taskType":{"const":"imageInference"},"taskUUID":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing","success","error"]},"imageUUID":{"type":"string","format":"uuid"},"imageURL":{"type":"string","format":"uri"},"imageBase64Data":{"type":"string"},"imageDataURI":{"type":"string"},"seed":{"type":"integer"},"NSFWContent":{"type":"boolean"},"cost":{"type":"number","description":"Amount deducted from your balance for this image (USD)."}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"parameter":{"type":"string"},"taskType":{"type":"string"},"taskUUID":{"type":"string","format":"uuid"},"documentation":{"type":"string"}}}}},"required":["errors"]}}},"paths":{"/uploads":{"post":{"summary":"Upload an input image","description":"Stores a JPEG, PNG or WEBP image (up to 20 MB) for 7 days and returns an imageUUID usable in inputs.","operationId":"uploadImage","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"taskType":{"const":"imageUpload"},"imageUUID":{"type":"string","format":"uuid"},"format":{"type":"string","enum":["JPG","PNG","WEBP"]},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid or corrupted image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Image too large or upload quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported image format or request content type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/":{"post":{"summary":"Run tasks","description":"POST an array of task objects (imageInference, getResponse, imageUpload, accountManagement, ping).","operationId":"runTasks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ImageInferenceTask"},{"$ref":"#/components/schemas/GetResponseTask"}]}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}},"errors":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"parameter":{"type":"string"},"taskType":{"type":"string"},"taskUUID":{"type":"string","format":"uuid"},"documentation":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request: missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required: insufficient balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: key disabled or model not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found: unknown taskUUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: duplicate taskUUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable: temporarily at capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Timeout: generation took too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}