{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Avelika Public API","version":"1.0.0","summary":"PHOTO generation and deterministic TEST request validation.","description":"The LIVE API uses the same Account, Workspace, generation admission, job and credit ledger as Avelika Workspace.\n\nTEST validation is an optional deployment feature. It validates authentication, idempotency and the PHOTO request contract without creating a job, reserving credits or calling a provider.\n\nProvider, model and raw prompt controls are intentionally not public.","contact":{"name":"Avelika Support","url":"https://www.avelika.com"}},"servers":[{"url":"https://app.avelika.com","description":"LIVE customer API"}],"tags":[{"name":"TEST","description":"Zero-provider request validation. Availability is deployment-controlled."},{"name":"PHOTO","description":"Asynchronous LIVE PHOTO generation."},{"name":"Jobs","description":"Account- and Workspace-scoped job status and results."}],"paths":{"/api/v1/test/validate":{"post":{"operationId":"validatePhotoRequest","tags":["TEST"],"summary":"Validate a PHOTO request without generation","description":"Requires AVELIKA_PUBLIC_API_TEST_MODE=enabled on the target deployment. Uses the canonical API key and request schema, but creates no job, performs no provider dispatch and changes no credit balance. This response is not a generation success.","security":[{"bearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePhotoRequest"}}}},"responses":{"200":{"description":"Request validated; no commercial operation occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestValidationResponse"}}}},"400":{"description":"Missing idempotency key or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked, expired or unauthorized API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"TEST validation is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Bounded internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/generate":{"post":{"operationId":"generatePhoto","tags":["PHOTO"],"summary":"Create an asynchronous PHOTO generation job","description":"LIVE operation. A newly admitted request may reserve credits and dispatch to the configured generation runtime. Replaying the same Idempotency-Key with the same request returns the same canonical operation; changing the request for that key returns idempotency_conflict.","security":[{"bearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePhotoRequest"}}}},"responses":{"202":{"description":"Accepted or idempotently replayed canonical job.","headers":{"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAcceptedResponse"}}}},"400":{"description":"Invalid PHOTO request or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked, expired or unauthorized API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The Account is not entitled to the requested output settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product analysis, source asset or concept was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency conflict, another generation in progress, or canonical request state conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"User or Workspace queue limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Bounded internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or generation service is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getPhotoJob","tags":["Jobs"],"summary":"Read a PHOTO job and its available results","description":"Returns only jobs created through the Public API session for the authenticated Account family and Workspace. UNKNOWN is unresolved/reconciliation-required and must not be blindly retried.","security":[{"bearerApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Canonical generation job ID."}],"responses":{"200":{"description":"Current job state and bounded result metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"400":{"description":"The job ID is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked, expired or unauthorized API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The job is missing or outside the authenticated Account/Workspace scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Bounded internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"avk_live_*","description":"Account/Workspace API key. Send only in Authorization: Bearer; never place it in a URL or browser bundle."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable client-generated key for one logical operation. Reuse it only for an exact retry.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"example":"catalog-2026-10-11-0001"}},"schemas":{"GeneratePhotoRequest":{"type":"object","additionalProperties":false,"required":["product_id","concept_id"],"properties":{"product_id":{"type":"string","format":"uuid","description":"Existing Product owned by the API key Workspace."},"concept_id":{"type":"string","minLength":1,"maxLength":160,"description":"Existing approved concept key for the Product."},"image_role":{"type":"string","enum":["main","alternate","detail","lifestyle","feature","dimensions","usage","packaging","on_model","comparison","swatch","infographic","other"],"default":"main"},"context":{"type":"object","additionalProperties":false,"properties":{"project_id":{"type":"string","format":"uuid"},"market":{"type":"string","pattern":"^[A-Z]{2}$","examples":["RU","DE"]},"marketplace":{"type":"string","minLength":1,"maxLength":64},"locale":{"type":"string","minLength":2,"maxLength":64,"examples":["ru-RU","en-US"]},"category":{"type":"string","minLength":1,"maxLength":120}}},"settings":{"type":"object","additionalProperties":false,"properties":{"aspect_ratio":{"type":"string","enum":["1:1","3:4","4:3","2:3","3:2","9:16","16:9"]},"quality":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"output_count":{"type":"integer","minimum":1,"maximum":4,"default":1}}},"confirmed_claim_ids":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","format":"uuid"}}},"example":{"product_id":"11111111-1111-4111-8111-111111111111","concept_id":"studio-clean","image_role":"main","context":{"market":"RU","locale":"ru-RU"},"settings":{"aspect_ratio":"3:4","quality":"1K","output_count":1}}},"GenerateAcceptedResponse":{"type":"object","additionalProperties":false,"required":["api_version","request_id","job_id","status","replayed"],"properties":{"api_version":{"const":"v1"},"request_id":{"type":"string","format":"uuid"},"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED","UNKNOWN"]},"replayed":{"type":"boolean"}}},"TestValidationResponse":{"type":"object","additionalProperties":false,"required":["api_version","mode","status","request_id","request_fingerprint","operation","dispatch","provider_calls","credits","limitations"],"properties":{"api_version":{"const":"v1"},"mode":{"const":"TEST"},"status":{"const":"VALIDATED"},"request_id":{"type":"string","format":"uuid"},"request_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"operation":{"const":"PHOTO"},"dispatch":{"const":false},"provider_calls":{"const":0},"credits":{"type":"object","additionalProperties":false,"required":["reserved","settled"],"properties":{"reserved":{"const":0},"settled":{"const":0}}},"limitations":{"type":"array","minItems":3,"items":{"type":"string"}}}},"JobResponse":{"type":"object","additionalProperties":false,"required":["api_version","job"],"properties":{"api_version":{"const":"v1"},"job":{"$ref":"#/components/schemas/Job"}}},"Job":{"type":"object","additionalProperties":false,"required":["id","product_id","concept_id","status","created_at","started_at","finished_at","error","outputs"],"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"concept_id":{"type":"string"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED","UNKNOWN"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"error":{"anyOf":[{"$ref":"#/components/schemas/JobError"},{"type":"null"}]},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/Output"}}}},"JobError":{"type":"object","additionalProperties":false,"required":["code"],"properties":{"code":{"type":"string","enum":["generation_failed","provider_outcome_unknown"]},"reconciling":{"type":"boolean"}}},"Output":{"type":"object","additionalProperties":false,"required":["id","asset_id","ordinal","url","url_expires_in","mime_type","width","height"],"properties":{"id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"ordinal":{"type":"integer","minimum":0},"url":{"type":"string","format":"uri","description":"Short-lived signed result URL."},"url_expires_in":{"type":"integer","const":900},"mime_type":{"type":["string","null"]},"width":{"type":["integer","null"],"minimum":1},"height":{"type":["integer","null"],"minimum":1}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}}}},"externalDocs":{"description":"Avelika API reference","url":"https://app.avelika.com/api-docs"},"x-avelika-i18n":{"supported":["en","ru"],"query_parameter":"lang"},"x-avelika-test":{"availability":"deployment-controlled","activation":"AVELIKA_PUBLIC_API_TEST_MODE=enabled","commercial_generation":false,"provider_calls":0,"credits":0}}