{"openapi":"3.1.0","info":{"title":"ImageLayer API","version":"1.0.0","description":"AI-powered branded image generation platform. Use this API to integrate ImageLayer into your application — create sessions for end-users, generate images from text/sketch/reference, composite with branding assets, and manage usage.","contact":{"name":"ImageLayer Support","url":"https://imagelayer.app"}},"servers":[{"url":"https://api.imagelayer.app","description":"Production"},{"url":"http://localhost:3001","description":"Local development"}],"tags":[{"name":"Authentication","description":"End-user session management"},{"name":"Generation","description":"AI image and video generation"},{"name":"Compositing","description":"Branded image compositing"},{"name":"Assets","description":"Layout and logo management"},{"name":"Configuration","description":"Widget configuration"},{"name":"Download","description":"Image download"},{"name":"Quota","description":"Usage and quota checking"},{"name":"Dashboard","description":"Organization dashboard data"},{"name":"Sub-accounts","description":"B2B sub-account management and white-label APIs"},{"name":"Billing","description":"Subscription and credit management"},{"name":"Organization Auth","description":"Organization registration and login"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Organization API key (starts with il_live_)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Session JWT (end-user) or Organization JWT (dashboard)"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid input"}},"required":["code","message"]}},"required":["error"]}},"parameters":{}},"paths":{"/v1/auth/session":{"post":{"tags":["Authentication"],"summary":"Create end-user session","description":"Authenticates an end-user and returns a session JWT. Creates the user if they do not exist yet. Call this from your backend with a secret API key; publishable widget keys are rejected.","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","minLength":1,"maxLength":255},"external_account_id":{"type":"string","maxLength":255},"display_name":{"type":"string","maxLength":255}},"required":["external_user_id"]}}}},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"session_token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"display_name":{"type":["string","null"]}},"required":["id","external_id","display_name"]}},"required":["session_token","expires_at","user"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/auth/admin-session":{"post":{"tags":["Authentication"],"summary":"Create sub-account admin session","description":"Returns a scoped admin JWT for a sub-account. Use this from your backend with a secret API key to power embedded settings, history, assets, analytics, or user-management surfaces.","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"external_account_id":{"type":"string","minLength":1,"maxLength":255},"permissions":{"type":"array","items":{"type":"string","enum":["settings","brand_assets","analytics","users","history"]},"minItems":1}},"required":["external_account_id","permissions"]}}}},"responses":{"201":{"description":"Admin session created","content":{"application/json":{"schema":{"type":"object","properties":{"admin_token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"sub_account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_account_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","external_account_id","name"]}},"required":["admin_token","expires_at","sub_account"]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Sub-account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/org/login":{"post":{"tags":["Organization Auth"],"summary":"Organization login","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":255,"format":"email"},"password":{"type":"string","minLength":1,"maxLength":255}},"required":["email","password"]}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"email":{"type":"string","format":"email"},"plan":{"type":"string"},"email_verified":{"type":"boolean"}},"required":["id","name","slug","email","plan","email_verified"]}},"required":["organization"]}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/org/register":{"post":{"tags":["Organization Auth"],"summary":"Register organization","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","maxLength":255,"format":"email"},"password":{"type":"string","minLength":8,"maxLength":255},"turnstile_token":{"type":"string","minLength":1,"maxLength":2048}},"required":["company","email","password"]}}}},"responses":{"201":{"description":"Organization created"},"409":{"description":"Email already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/org/google/start":{"post":{"tags":["Organization Auth"],"summary":"Start Google organization auth","description":"Starts the Google sign-in or sign-up flow for organization owners and returns the Google authorization URL.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["login","register","login_or_create"]},"redirect_origin":{"type":"string","maxLength":255,"format":"uri"},"next":{"type":"string","maxLength":500},"plan":{"type":"string","enum":["starter","pro"]},"turnstile_token":{"type":"string","minLength":1,"maxLength":2048}},"required":["mode"]}}}},"responses":{"200":{"description":"Google authorization URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"authorization_url":{"type":"string","format":"uri"}},"required":["authorization_url"]}}}},"400":{"description":"Invalid auth request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Google auth unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/org/google/exchange":{"post":{"tags":["Organization Auth"],"summary":"Exchange Google auth handoff for org tokens","description":"Finalizes a successful Google sign-in or sign-up flow and returns organization access tokens.","responses":{"200":{"description":"Google organization auth completed","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"email":{"type":"string","format":"email"},"plan":{"type":"string"},"email_verified":{"type":"boolean"}},"required":["id","name","slug","email","plan","email_verified"]},"is_new":{"type":"boolean"},"next_path":{"type":["string","null"]},"selected_plan":{"type":["string","null"],"enum":["starter","pro",null]}},"required":["organization","is_new","next_path","selected_plan"]}}}},"401":{"description":"Google auth handoff missing or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/campaigns":{"post":{"tags":["Campaigns"],"summary":"Create campaign bundle","description":"Creates a campaign group and queues one generation request per campaign item. Requires organization API key and end-user session token.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preset_id":{"type":"string","enum":["local_business_promo_pack","b2b_advocacy_pack"]},"source_context":{"type":"object","properties":{"sourceType":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"audience":{"type":"string"}},"required":["sourceType"]},"goal":{"type":"string"},"channels":{"type":"array","items":{"type":"string"},"minItems":1},"audiences":{"type":"array","items":{"type":"string"}},"host_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["preset_id","source_context","goal","channels"]}}}},"responses":{"202":{"description":"Campaign accepted","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"estimated_credits":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"channel":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"estimated_credits":{"type":"integer"}},"required":["id","key","channel","output_mode","estimated_credits"]}},"poll_url":{"type":"string"}},"required":["campaign_id","status","estimated_credits","items","poll_url"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Quota or rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get campaign detail","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Campaign detail","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"preset_id":{"type":"string"},"status":{"type":"string"},"source_context":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"goal":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"audiences":{"type":"array","items":{"type":"string"}},"estimated_credits":{"type":"integer"},"credits_used":{"type":"integer"},"item_count":{"type":"integer"},"completed_item_count":{"type":"integer"},"failed_item_count":{"type":"integer"},"failure_summary":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"host_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"submitted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":["string","null"]},"role":{"type":["string","null"]},"channel":{"type":["string","null"]},"status":{"type":["string","null"]},"generation_status":{"type":"string"},"output_mode":{"type":"string"},"generated_text":{"type":["string","null"]},"image_key":{"type":["string","null"]},"image_url":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"required":["id","key","role","channel","status","generation_status","output_mode","generated_text","image_key","image_url","error_code","error_message","created_at","completed_at"]}}},"required":["campaign_id","preset_id","status","source_context","goal","channels","audiences","estimated_credits","credits_used","item_count","completed_item_count","failed_item_count","failure_summary","host_metadata","submitted_at","created_at","updated_at","items"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/campaigns/{id}/items/{itemId}/regenerate":{"post":{"tags":["Campaigns"],"summary":"Regenerate campaign item","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instructions":{"type":"string","maxLength":1000},"host_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}}}}},"responses":{"202":{"description":"Campaign item regeneration queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]},"poll_url":{"type":"string"}},"required":["id","status","poll_url"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/campaigns/{id}/submit":{"post":{"tags":["Campaigns"],"summary":"Submit selected campaign assets","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_assets":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"generation_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["item_id"]},"minItems":1},"host_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["selected_assets"]}}}},"responses":{"200":{"description":"Campaign submitted","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted"]},"selected_assets":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"generation_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["item_id"]},"minItems":1}},"required":["campaign_id","status","selected_assets"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/generate":{"post":{"tags":["Generation"],"summary":"Create generation","description":"Starts an asynchronous generation job. Supports image, text, video, and audio generation. Returns a poll URL for status.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["text","sketch","reference"]},"prompt":{"type":"string","minLength":1,"maxLength":8000},"output_mode":{"type":"string","enum":["image","text","video","audio"],"default":"image"},"model":{"type":"string","maxLength":100},"use_brand_guidelines":{"type":"boolean","default":false},"generate_text":{"type":"boolean"},"text_language":{"type":"string","minLength":2,"maxLength":10},"aspect_ratio":{"type":"string","maxLength":10,"pattern":"^\\d{1,2}(?:\\.\\d{1,2})?:\\d{1,2}(?:\\.\\d{1,2})?$"},"image_output_resolution":{"type":"string","enum":["1K","2K","4K"]},"seed":{"type":"integer","minimum":1,"maximum":2147483647},"content_type":{"type":"string","maxLength":100},"content_type_fields":{"type":"object","additionalProperties":{"type":"string","maxLength":5000}},"platform_preset":{"type":"string","maxLength":50},"video_duration":{"type":"number"},"video_resolution":{"type":"string","enum":["720p","1080p"]},"audio_voice":{"type":"string","enum":["Kore","Puck","Charon","Aoede","Sulafat","Achird","Leda","Sadaltager","alloy","echo","fable","onyx","nova","shimmer"]},"audio_duration":{"type":"number","minimum":5,"maximum":300},"audio_format":{"type":"string","enum":["mp3","wav"]},"podcast_format":{"type":"string","enum":["monologue","two-host","interview"]}},"required":["type"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["text","sketch","reference"]},"prompt":{"type":"string"},"model":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"],"description":"Output type."},"use_brand_guidelines":{"type":"string","description":"\"true\" or \"false\""},"generate_text":{"type":"string"},"text_language":{"type":"string"},"aspect_ratio":{"type":"string"},"image_output_resolution":{"type":"string","enum":["1K","2K","4K"],"description":"Gemini image output resolution. Defaults to 1K."},"content_type":{"type":"string"},"content_type_fields":{"type":"string","description":"JSON string of key-value pairs"},"platform_preset":{"type":"string"},"video_duration":{"type":"number","description":"Video duration in seconds (4, 6, or 8). Only for output_mode \"video\"."},"video_resolution":{"type":"string","enum":["720p","1080p"],"description":"Video resolution. Plan limits may apply."},"sketch":{"type":"string","format":"binary","description":"Sketch image file"},"references":{"type":"array","items":{"type":"string","format":"binary"},"description":"Reference image files (max 5). For video, the first reference is used as the source frame."}}}}}},"responses":{"202":{"description":"Generation queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]},"estimated_seconds":{"type":"number"},"queue_position":{"type":"integer","exclusiveMinimum":0},"queue_depth":{"type":"integer","exclusiveMinimum":0},"queue_type":{"type":"string","enum":["image","text","video","audio"]},"poll_url":{"type":"string"}},"required":["id","status","estimated_seconds","queue_position","queue_depth","queue_type","poll_url"]}}}},"400":{"description":"Validation error or prompt rejected by moderation policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/generate/{id}/status":{"get":{"tags":["Generation"],"summary":"Get generation status","description":"Poll this endpoint to check whether a generation has completed. Returns the image/video URL when done.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Generation status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","generating","completed","failed","blocked","expired"]},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"image_url":{"type":["string","null"],"description":"Image or video URL when completed"},"generated_text":{"type":["string","null"]},"image_width":{"type":["number","null"]},"image_height":{"type":["number","null"]},"video_duration":{"type":["number","null"],"description":"Video duration in seconds (only for video output)"},"estimated_seconds":{"type":["number","null"],"description":"Approximate queue wait remaining while work is still in progress"},"queue_position":{"type":["integer","null"],"description":"Approximate position among queued jobs when the request is still waiting"},"queue_depth":{"type":["integer","null"],"description":"Current global queue depth for the active queue type"},"queue_type":{"type":["string","null"],"enum":["image","text","video","audio",null]},"alt_text":{"type":["string","null"],"description":"AI-generated alt text for image outputs when available."},"audio_url":{"type":["string","null"]},"audio_voice":{"type":["string","null"]},"audio_duration":{"type":["number","null"]},"audio_format":{"type":["string","null"]},"voiceover_status":{"type":"string","enum":["idle","pending","generating","completed","failed"]},"voiceover_error_message":{"type":["string","null"]},"prompt_moderation_warning":{"type":"boolean"},"prompt_moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"prompt_moderation_reason":{"type":["string","null"]},"moderation_warning":{"type":"boolean","description":"True when moderation is configured in warn-only mode and the content was flagged"},"moderation_categories":{"type":["array","null"],"items":{"type":"string"},"description":"Matched moderation categories, if any"},"cost_cents":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]}},"required":["id","status","output_mode","image_url","generated_text","image_width","image_height","video_duration","alt_text","moderation_warning","moderation_categories","cost_cents","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/generate/{id}/voiceover":{"post":{"tags":["Generation"],"summary":"Queue video voiceover","description":"Queues or re-runs a voiceover job for an existing completed video generation and returns the same poll URL used by status checks.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"type":"string","enum":["Kore","Puck","Charon","Aoede","Sulafat","Achird","Leda","Sadaltager","alloy","echo","fable","onyx","nova","shimmer"]},"prompt":{"type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"202":{"description":"Voiceover queued or already processing","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"voiceover_status":{"type":"string","enum":["pending","generating"]},"estimated_seconds":{"type":"number"},"queue_position":{"type":"integer","exclusiveMinimum":0},"queue_depth":{"type":"integer","exclusiveMinimum":0},"queue_type":{"type":"string","enum":["audio"]},"poll_url":{"type":"string"}},"required":["id","voiceover_status","poll_url"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Voiceover queue unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/generate/{id}/analyze":{"post":{"tags":["Generation"],"summary":"Analyze generated asset with Gemma","description":"Runs on-demand OCR, captioning, tagging, and brand/compliance review for a completed image or video generation.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Structured Gemma analysis","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"output_mode":{"type":"string","enum":["image","video"]},"summary":{"type":"string"},"caption":{"type":"string"},"extracted_text":{"type":["string","null"]},"language":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"brand_elements":{"type":"array","items":{"type":"string"}},"compliance_notes":{"type":"array","items":{"type":"string"}}},"required":["id","output_mode","summary","caption","extracted_text","language","tags","brand_elements","compliance_notes"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Analysis unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/generate/history":{"get":{"tags":["Generation"],"summary":"List recent credits","description":"Returns the current user's generation history within the TTL window.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["image","text","video","audio"]},"required":false,"name":"output_mode","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaign_id","in":"query"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["auto","keyword","semantic"],"default":"auto"},"required":false,"name":"search_mode","in":"query"}],"responses":{"200":{"description":"Generation history","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"prompt":{"type":["string","null"]},"status":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"image_url":{"type":["string","null"]},"video_url":{"type":["string","null"]},"generated_text":{"type":["string","null"]},"alt_text":{"type":["string","null"]},"prompt_moderation_warning":{"type":"boolean"},"prompt_moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"prompt_moderation_reason":{"type":["string","null"]},"moderation_warning":{"type":"boolean"},"moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"audio_url":{"type":["string","null"]},"audio_voice":{"type":["string","null"]},"voiceover_status":{"type":"string","enum":["idle","pending","generating","completed","failed"]},"voiceover_error_message":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"campaign":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"preset_id":{"type":"string"},"status":{"type":"string"},"item_count":{"type":"integer"},"completed_item_count":{"type":"integer"},"failed_item_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","preset_id","status","item_count","completed_item_count","failed_item_count","created_at"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","prompt","status","output_mode","created_at"]}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"]}}}}}}},"/v1/sub-accounts/me/history":{"get":{"tags":["Sub-accounts"],"summary":"List sub-account history","description":"Lists generation history for the sub-account represented by a scoped admin token. Requires X-API-Key plus a Bearer admin token with the history permission.","security":[{"ApiKeyAuth":[],"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["image","text","video","audio"]},"required":false,"name":"output_mode","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaign_id","in":"query"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["auto","keyword","semantic"],"default":"auto"},"required":false,"name":"search_mode","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"external_user_id","in":"query"}],"responses":{"200":{"description":"Sub-account generation history","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"prompt":{"type":["string","null"]},"status":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"image_url":{"type":["string","null"]},"video_url":{"type":["string","null"]},"generated_text":{"type":["string","null"]},"alt_text":{"type":["string","null"]},"prompt_moderation_warning":{"type":"boolean"},"prompt_moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"prompt_moderation_reason":{"type":["string","null"]},"moderation_warning":{"type":"boolean"},"moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"audio_url":{"type":["string","null"]},"audio_voice":{"type":["string","null"]},"voiceover_status":{"type":"string","enum":["idle","pending","generating","completed","failed"]},"voiceover_error_message":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"campaign":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"preset_id":{"type":"string"},"status":{"type":"string"},"item_count":{"type":"integer"},"completed_item_count":{"type":"integer"},"failed_item_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","preset_id","status","item_count","completed_item_count","failed_item_count","created_at"]},"created_at":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"display_name":{"type":["string","null"]}},"required":["id","external_id","display_name"]}},"required":["id","type","prompt","status","output_mode","created_at"]}},"next_cursor":{"type":["string","null"]},"search_note":{"type":"string"}},"required":["items","next_cursor"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Admin token lacks history permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/sub-accounts/{id}/history":{"get":{"tags":["Sub-accounts"],"summary":"List history for a sub-account","description":"Server-side API-key endpoint for platform integrators to build their own white-label history UI.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["image","text","video","audio"]},"required":false,"name":"output_mode","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaign_id","in":"query"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["auto","keyword","semantic"],"default":"auto"},"required":false,"name":"search_mode","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"external_user_id","in":"query"}],"responses":{"200":{"description":"Sub-account generation history","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"prompt":{"type":["string","null"]},"status":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"image_url":{"type":["string","null"]},"video_url":{"type":["string","null"]},"generated_text":{"type":["string","null"]},"alt_text":{"type":["string","null"]},"prompt_moderation_warning":{"type":"boolean"},"prompt_moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"prompt_moderation_reason":{"type":["string","null"]},"moderation_warning":{"type":"boolean"},"moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"audio_url":{"type":["string","null"]},"audio_voice":{"type":["string","null"]},"voiceover_status":{"type":"string","enum":["idle","pending","generating","completed","failed"]},"voiceover_error_message":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"campaign":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"preset_id":{"type":"string"},"status":{"type":"string"},"item_count":{"type":"integer"},"completed_item_count":{"type":"integer"},"failed_item_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","preset_id","status","item_count","completed_item_count","failed_item_count","created_at"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","prompt","status","output_mode","created_at"]}},"next_cursor":{"type":["string","null"]},"search_note":{"type":"string"}},"required":["items","next_cursor"]}}}},"404":{"description":"Sub-account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/dashboard/generations/history":{"get":{"tags":["Dashboard"],"summary":"List dashboard generation history","description":"Cursor-paginated dashboard history with retention metadata, seed metadata, media filters, and semantic search.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["image","text","video","audio"]},"required":false,"name":"output_mode","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaign_id","in":"query"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["auto","keyword","semantic"],"default":"auto"},"required":false,"name":"search_mode","in":"query"}],"responses":{"200":{"description":"Dashboard generation history","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"prompt":{"type":["string","null"]},"status":{"type":"string"},"output_mode":{"type":"string","enum":["image","text","video","audio"]},"image_url":{"type":["string","null"]},"video_url":{"type":["string","null"]},"generated_text":{"type":["string","null"]},"alt_text":{"type":["string","null"]},"prompt_moderation_warning":{"type":"boolean"},"prompt_moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"prompt_moderation_reason":{"type":["string","null"]},"moderation_warning":{"type":"boolean"},"moderation_categories":{"type":["array","null"],"items":{"type":"string"}},"audio_url":{"type":["string","null"]},"audio_voice":{"type":["string","null"]},"voiceover_status":{"type":"string","enum":["idle","pending","generating","completed","failed"]},"voiceover_error_message":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"campaign":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"preset_id":{"type":"string"},"status":{"type":"string"},"item_count":{"type":"integer"},"completed_item_count":{"type":"integer"},"failed_item_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","preset_id","status","item_count","completed_item_count","failed_item_count","created_at"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","prompt","status","output_mode","created_at"]}},"next_cursor":{"type":["string","null"]},"search_note":{"type":"string"}},"required":["items","next_cursor"]}}}}}}},"/v1/dashboard/generations/{id}":{"delete":{"tags":["Dashboard"],"summary":"Remove a generation from dashboard history","description":"Soft-hides a completed, failed, or expired generation from dashboard history while preserving usage and audit records.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Generation hidden from dashboard history"},"400":{"description":"Generation status cannot be removed from history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Generation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/composite":{"post":{"tags":["Compositing"],"summary":"Create branded composite","description":"Combines a generated image with layout and logo assets to produce a branded composite image with a download link.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"generation_id":{"type":"string","format":"uuid"},"layout_asset_id":{"type":["string","null"],"format":"uuid"},"logo_asset_id":{"type":["string","null"],"format":"uuid"},"logo_position":{"type":["object","null"],"properties":{"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"width":{"type":"number","minimum":0,"maximum":1},"height":{"type":"number","minimum":0,"maximum":1}},"required":["x","y","width","height"]},"output_format":{"type":"string","enum":["png","jpeg","webp"]},"output_width":{"type":"integer","minimum":64,"maximum":2048},"output_height":{"type":"integer","minimum":64,"maximum":2048}},"required":["generation_id","layout_asset_id","logo_asset_id","logo_position","output_format","output_width","output_height"]}}}},"responses":{"201":{"description":"Composite created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"download_url":{"type":"string"},"download_expires_at":{"type":"string"},"format":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"file_size":{"type":"number"}},"required":["id","download_url","download_expires_at","format","width","height","file_size"]}}}},"404":{"description":"Generation or asset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/assets":{"get":{"tags":["Assets"],"summary":"List branding assets","description":"Returns layout and logo assets for the authenticated user/organization.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["layout","logo","brand_reference"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Asset list","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"filename":{"type":"string"},"thumbnail_url":{"type":"string"},"scope":{"type":"string","enum":["user","organization"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","filename","thumbnail_url","scope","width","height","created_at"]}}},"required":["items"]}}}}}},"post":{"tags":["Assets"],"summary":"Upload branding asset","description":"Uploads a layout or logo image for use in compositing.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"type":{"type":"string","enum":["layout","logo","brand_reference"]}},"required":["type"]}}}},"responses":{"201":{"description":"Asset uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"filename":{"type":"string"},"url":{"type":"string"},"scope":{"type":"string","enum":["user"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]}},"required":["id","type","filename","url","scope","width","height"]}}}}}}},"/v1/assets/{id}":{"delete":{"tags":["Assets"],"summary":"Delete branding asset","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"}}}},"/v1/assets/{id}/analyze":{"post":{"tags":["Assets"],"summary":"Analyze uploaded asset with Gemma","description":"Runs OCR, captioning, tagging, and brand/compliance review for a stored branding or reference asset.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Structured Gemma analysis","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"filename":{"type":"string"},"summary":{"type":"string"},"caption":{"type":"string"},"extracted_text":{"type":["string","null"]},"language":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"brand_elements":{"type":"array","items":{"type":"string"}},"compliance_notes":{"type":"array","items":{"type":"string"}}},"required":["id","type","filename","summary","caption","extracted_text","language","tags","brand_elements","compliance_notes"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Analysis unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/config":{"get":{"tags":["Configuration"],"summary":"Get widget configuration","description":"Returns customization settings, feature flags, and limits for the widget. Used by the <image-layer> web component at initialization.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Widget config","content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"org_name":{"type":"string"},"available_output_modes":{"type":"array","items":{"type":"string","enum":["image","text","video","audio"]}},"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"provider":{"type":"string"},"description":{"type":"string"},"supports_images":{"type":"boolean"},"supports_brand_guidelines":{"type":"boolean"},"output_mode":{"type":"string","enum":["image","text","video","audio"]}},"required":["id","label","provider","description","supports_images","supports_brand_guidelines","output_mode"]}},"default_model":{"type":"string"},"features":{"type":"object","properties":{"text_generation":{"type":"boolean"},"sketch_generation":{"type":"boolean"},"reference_generation":{"type":"boolean"},"video_generation":{"type":"boolean"},"content_moderation":{"type":"boolean"},"prompt_enhancement":{"type":"boolean"},"asset_analysis":{"type":"boolean"},"ai_summary":{"type":"boolean"},"ai_summary_extended":{"type":"boolean"},"branding":{"type":"boolean"},"history":{"type":"boolean"},"brand_guidelines":{"type":"boolean"},"ai_text_generation":{"type":"boolean"},"campaign_generation":{"type":"boolean"}},"required":["text_generation","sketch_generation","reference_generation","video_generation","content_moderation","branding","history","brand_guidelines"]},"content_types":{"type":["object","null"],"properties":{"enabled":{"type":"boolean"},"types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"placeholder":{"type":"string"},"required":{"type":"boolean"},"maxLength":{"type":"number"}},"required":["name","label","type","placeholder","required"]}},"icon":{"type":"string"},"builtIn":{"type":"boolean"}},"required":["id","name","description","fields","icon","builtIn"]}}},"required":["enabled","types"]},"text_content_types":{"type":["object","null"],"properties":{"enabled":{"type":"boolean"},"types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"placeholder":{"type":"string"},"required":{"type":"boolean"},"maxLength":{"type":"number"}},"required":["name","label","type","placeholder","required"]}},"icon":{"type":"string"},"builtIn":{"type":"boolean"}},"required":["id","name","description","fields","icon","builtIn"]}}},"required":["enabled","types"]},"video_content_types":{"type":["object","null"],"properties":{"enabled":{"type":"boolean"},"types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"placeholder":{"type":"string"},"required":{"type":"boolean"},"maxLength":{"type":"number"}},"required":["name","label","type","placeholder","required"]}},"icon":{"type":"string"},"builtIn":{"type":"boolean"}},"required":["id","name","description","fields","icon","builtIn"]}}},"required":["enabled","types"]},"suggested_prompts":{"type":["object","null"],"properties":{"image":{"type":"array","items":{"type":"string"}},"text":{"type":"array","items":{"type":"string"}}}},"platform_presets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"aspect_ratio":{"type":["string","null"]},"icon":{"type":"string"}},"required":["id","name","platform","width","height","aspect_ratio","icon"]}},"campaign_presets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["local_business_promo_pack","b2b_advocacy_pack"]},"name":{"type":"string"},"description":{"type":"string"},"source_types":{"type":"array","items":{"type":"string"}},"source_requirements":{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"goals":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"outputs":{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"max_items":{"type":"integer"},"credit_estimate":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["id","name","description","source_types","source_requirements","goals","channels","outputs","max_items","credit_estimate"]}},"campaign_config":{"type":["object","null"],"properties":{"tab_label":{"type":"string"},"default_preset":{"type":["string","null"],"enum":["local_business_promo_pack","b2b_advocacy_pack",null]},"max_items":{"type":"integer"},"show_campaign_history":{"type":"boolean"},"default_tab":{"type":"string","enum":["generate","campaign"]}},"required":["tab_label","default_preset","max_items","show_campaign_history"]},"animation_style":{"type":"string"},"customization":{"type":"object","properties":{"primary_color":{"type":"string"},"accent_color":{"type":"string"},"font_family":{"type":"string"},"border_radius":{"type":"string"},"labels":{"type":"object","properties":{"generate_button":{"type":"string"},"submit_button":{"type":"string"},"prompt_placeholder":{"type":"string"}},"required":["generate_button","submit_button","prompt_placeholder"]}},"required":["primary_color","accent_color","font_family","border_radius","labels"]},"text_generation":{"type":["object","null"],"properties":{"default_language":{"type":"string"},"default_tone":{"type":"string"},"default_length":{"type":"string"}},"required":["default_language","default_tone","default_length"]},"audio_config":{"type":["object","null"],"properties":{"default_model":{"type":"string"},"voices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"style":{"type":"string"},"gender":{"type":"string","enum":["M","F"]}},"required":["id","label","style","gender"]}},"max_duration":{"type":"number"},"podcast_enabled":{"type":"boolean"}},"required":["default_model","voices","max_duration","podcast_enabled"]},"limits":{"type":"object","properties":{"max_generations_per_day":{"type":"number"},"max_references":{"type":"number"},"max_output_resolution":{"type":"number"}},"required":["max_references","max_output_resolution"]}},"required":["org_id","org_name","features","customization","limits"]}}}}}}},"/v1/download/{token}":{"get":{"tags":["Download"],"summary":"Download composite image","description":"Download a composite image using a time-limited token. No authentication required — token serves as proof of authorization.","parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Image file (binary)","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/quota/status":{"get":{"tags":["Quota"],"summary":"Check quota status","description":"Returns the current usage and remaining quota for the organization. Use this to check whether the widget should be shown before initializing it.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Quota status","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean"},"current":{"type":"number"},"plan_limit":{"type":"number"},"purchased_credits":{"type":"number"},"purchased_remaining":{"type":"number"},"total_limit":{"type":"number"},"remaining":{"type":"number"},"usage_percent":{"type":"number"},"warning_level":{"type":["number","null"]},"plan":{"type":"string"},"usage_period_start":{"type":"string","format":"date-time"},"usage_period_end":{"type":"string","format":"date-time"},"resets_at":{"type":"string","format":"date-time"},"period_label":{"type":"string"},"period_type":{"type":"string","enum":["billing_cycle","calendar_month"]}},"required":["allowed","current","plan_limit","purchased_credits","purchased_remaining","total_limit","remaining","usage_percent","warning_level","plan","usage_period_start","usage_period_end","resets_at","period_label","period_type"]}}}}}}},"/v1/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns API status. Pass ?deep=true for database and Redis connectivity checks (may require HEALTH_CHECK_KEY).","responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"timestamp":{"type":"string","format":"date-time"}},"required":["status","timestamp"]}}}},"503":{"description":"Service unhealthy"}}}},"/v1/feedback":{"post":{"tags":["Feedback"],"summary":"Submit bug report or feedback","description":"Submit a bug report with optional screenshot. Authenticated via API key + session.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["bug","feedback","feature_request"]},"message":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["type","message"]}}}},"responses":{"204":{"description":"Feedback submitted"}}}},"/v1/dashboard/usage":{"get":{"tags":["Dashboard"],"summary":"Get usage analytics","description":"Returns aggregated usage data for the organization within a date range.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":true,"name":"to","in":"query"},{"schema":{"type":"string","enum":["day","week","month"],"default":"day"},"required":false,"name":"group_by","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"default":"UTC"},"required":false,"name":"timezone","in":"query"}],"responses":{"200":{"description":"Usage data"}}}},"/v1/dashboard/usage/by-account":{"get":{"tags":["Dashboard"],"summary":"Get usage by sub-account","description":"Returns usage grouped by external_account_id. Use this to bill your own sub-accounts for their ImageLayer usage.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":true,"name":"to","in":"query"},{"schema":{"type":"string","enum":["day","week","month"],"default":"day"},"required":false,"name":"group_by","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"default":"UTC"},"required":false,"name":"timezone","in":"query"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"account_id","in":"query"}],"responses":{"200":{"description":"Usage grouped by account","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"string"},"credits":{"type":"number"},"unique_users":{"type":"number"},"cost_cents":{"type":"number"}},"required":["account_id","credits","unique_users","cost_cents"]}},"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]}},"required":["accounts","period"]}}}}}}},"/v1/dashboard/users":{"get":{"tags":["Dashboard"],"summary":"List end users","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Users list"}}}},"/v1/dashboard/api-keys":{"get":{"tags":["Dashboard"],"summary":"List API keys","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"API keys list"}}},"post":{"tags":["Dashboard"],"summary":"Create API key","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["secret","publishable"],"default":"secret"},"allowed_origins":{"type":"array","items":{"type":"string","maxLength":255,"format":"uri"},"maxItems":20}},"required":["label"]}}}},"responses":{"201":{"description":"API key created (includes raw key — shown once only)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"label":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","key","label","created_at"]}}}}}}},"/v1/dashboard/api-keys/{id}":{"delete":{"tags":["Dashboard"],"summary":"Revoke API key","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Key revoked"}}}},"/v1/dashboard/credits":{"get":{"tags":["Dashboard"],"summary":"Get credits and usage status","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Credits and usage info"}}}},"/v1/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create subscription checkout","description":"Creates a LemonSqueezy checkout URL for a subscription plan upgrade.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","pro"]}},"required":["plan"]}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"}},"required":["checkout_url"]}}}}}}},"/v1/billing/credits/checkout":{"post":{"tags":["Billing"],"summary":"Create credit pack checkout","description":"Creates a one-time checkout for a credit pack.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pack_id":{"type":"string","minLength":1}},"required":["pack_id"]}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"}},"required":["checkout_url"]}}}}}}},"/v1/billing/storage/checkout":{"post":{"tags":["Billing"],"summary":"Create storage add-on checkout","description":"Creates a recurring LemonSqueezy checkout URL for archive storage add-ons.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pack_id":{"type":"string","enum":["archive_100gb"]}},"required":["pack_id"]}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"}},"required":["checkout_url"]}}}}}}},"/v1/billing/portal":{"post":{"tags":["Billing"],"summary":"Get customer portal URL","description":"Returns the LemonSqueezy customer portal URL for managing subscriptions.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"portal_url":{"type":"string","format":"uri"}},"required":["portal_url"]}}}}}}}},"webhooks":{}}