{"openapi":"3.1.0","info":{"title":"AI.Images API","version":"1.1.0","description":"Sovereign, versioned image generation and editing API. Every consumer uses its own revocable Bearer credential."},"servers":[{"url":"/","description":"Current origin"}],"tags":[{"name":"System"},{"name":"Images"},{"name":"Jobs"}],"paths":{"/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Process liveness","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/ready":{"get":{"tags":["System"],"operationId":"getReadiness","summary":"Runtime readiness","responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/openapi.json":{"get":{"tags":["System"],"operationId":"getOpenApi","summary":"OpenAPI contract","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/api/v1/capabilities":{"get":{"tags":["System"],"operationId":"getCapabilities","summary":"Provider and API capabilities","responses":{"200":{"description":"Capabilities","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/images/generate":{"post":{"tags":["Images"],"operationId":"generateImage","summary":"Generate an image synchronously","description":"Send Prefer: respond-async to receive a Job instead. Seed is documented as unsupported and returns 422 when supplied.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PreferAsync"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"200":{"description":"Completed image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"}}}},"202":{"description":"Accepted asynchronous job","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/api/v1/images/edit":{"post":{"tags":["Images"],"operationId":"editImage","summary":"Edit using reference images and an optional mask","description":"Up to four reference images. A mask applies to the first image and must be a same-size PNG with alpha.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PreferAsync"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}},"responses":{"200":{"description":"Completed image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"}}}},"202":{"description":"Accepted asynchronous job","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/api/v1/jobs/generate":{"post":{"tags":["Jobs"],"operationId":"createGenerateJob","summary":"Queue image generation","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"202":{"description":"Accepted asynchronous job","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/api/v1/jobs/edit":{"post":{"tags":["Jobs"],"operationId":"createEditJob","summary":"Queue image editing","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}},"responses":{"202":{"description":"Accepted asynchronous job","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}},"/api/v1/jobs/{jobId}":{"get":{"tags":["Jobs"],"operationId":"getJob","summary":"Read a job owned by the authenticated client","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Job state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/jobs/{jobId}/artifact":{"get":{"tags":["Jobs"],"operationId":"downloadJobArtifact","summary":"Download a completed artifact","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Image bytes","headers":{"X-Content-SHA256":{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"content":{"image/png":{"schema":{"type":"string","contentEncoding":"binary"}},"image/jpeg":{"schema":{"type":"string","contentEncoding":"binary"}},"image/webp":{"schema":{"type":"string","contentEncoding":"binary"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"client-specific opaque token","description":"Distinct token for UI, Forge, Studio3D, or Warden."}},"parameters":{"PreferAsync":{"name":"Prefer","in":"header","required":false,"schema":{"type":"string","enum":["respond-async"]}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"JobId":{"name":"jobId","in":"path","required":true,"schema":{"type":"string","pattern":"^job_[0-9a-f-]{36}$"}}},"schemas":{"Status":{"type":"object","additionalProperties":false,"required":["status","service","version","commit"],"properties":{"status":{"type":"string","enum":["ok","ready"]},"service":{"type":"string","const":"AI.Images"},"version":{"type":"string","const":"1.1.0"},"commit":{"type":"string"}}},"AdvancedOptions":{"type":"object","properties":{"style":{"type":"string","minLength":1,"maxLength":200},"camera":{"type":"string","minLength":1,"maxLength":200},"purpose":{"type":"string","minLength":1,"maxLength":200},"slot":{"type":"string","minLength":1,"maxLength":200},"seed":{"type":"integer","deprecated":true,"description":"Reserved. The current provider does not support seed and returns 422."}}},"GenerateRequest":{"type":"object","additionalProperties":false,"required":["prompt","size","quality"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000},"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"]},"quality":{"type":"string","enum":["low","medium","high"]},"style":{"type":"string","minLength":1,"maxLength":200},"camera":{"type":"string","minLength":1,"maxLength":200},"purpose":{"type":"string","minLength":1,"maxLength":200},"slot":{"type":"string","minLength":1,"maxLength":200},"seed":{"type":"integer","deprecated":true,"description":"Reserved. The current provider does not support seed and returns 422."}}},"EditRequest":{"type":"object","additionalProperties":false,"required":["prompt","size","quality","image"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000},"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"]},"quality":{"type":"string","enum":["low","medium","high"]},"style":{"type":"string","maxLength":200},"camera":{"type":"string","maxLength":200},"purpose":{"type":"string","maxLength":200},"slot":{"type":"string","maxLength":200},"image":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","format":"binary"}},"mask":{"type":"string","format":"binary","description":"Same dimensions and PNG format as the first image; must contain alpha."}}},"ImageData":{"type":"object","additionalProperties":false,"required":["mimeType","width","height","sha256","base64"],"properties":{"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"base64":{"type":"string","contentEncoding":"base64"}}},"ImageResponse":{"type":"object","additionalProperties":false,"required":["id","createdAt","model","operation","prompt","size","quality","image"],"properties":{"id":{"type":"string","pattern":"^img_[0-9a-f-]{36}$"},"createdAt":{"type":"string","format":"date-time"},"model":{"type":"string"},"operation":{"type":"string","enum":["generate","edit"]},"prompt":{"type":"string"},"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"]},"quality":{"type":"string","enum":["low","medium","high"]},"style":{"type":"string"},"camera":{"type":"string"},"purpose":{"type":"string"},"slot":{"type":"string"},"image":{"$ref":"#/components/schemas/ImageData"}}},"Job":{"type":"object","additionalProperties":false,"required":["id","clientId","operation","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","pattern":"^job_[0-9a-f-]{36}$"},"clientId":{"type":"string","enum":["ui","forge","studio3d","warden"]},"operation":{"type":"string","enum":["generate","edit"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"idempotencyKey":{"type":"string"},"result":{"type":"object","properties":{"mimeType":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"sha256":{"type":"string"},"artifactUrl":{"type":"string"}}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}